Customer connections

Choose route names that match the product, and implement these behaviors.

Connect#

1. Require an authenticated customer administrator and the product's normal CSRF protection for the connect action. Derive the customer ID from trusted authentication context, never an arbitrary tenant ID supplied by the model or browser.
2. Create a cryptographically random OAuth state and a short-lived pending attempt bound to that customer, the initiating session, and the expected issuer.
3. Persist the SDK's PKCE verifier and discovery state with the attempt so the flow survives a server restart. Expire attempts after ten minutes and invalidate superseded attempts for that customer.
4. Redirect the customer to Dativue to sign in or create an account and approve research using their credits.

Request only research:read; do not add offline_access, which Dativue does not advertise. Include resource=https://dativue.com/mcp in authorization and token requests through the SDK.

Exercise Connect in a real browser, including the product's content security policy, CSRF checks, and session cookies. If a form submission redirects to Dativue, a form-action 'self' policy can block the redirect even when the backend returns HTTP 303 successfully. Allow the exact discovered and validated Dativue authorization origin in the relevant form policy, preserving the product's other protections and avoiding wildcard destinations.

Callback and free verification#

1. Require the same authenticated administrator session that initiated the attempt. Validate customer ownership, session binding, state, expiration, and the authorization server's iss parameter before exchanging a code.
2. Consume the attempt atomically before network activity to reject replay.
3. Give the SDK the entire callback query, including iss, rather than passing just the authorization code. Treat cancellation as a cancelled connection, and do not display untrusted callback error descriptions.
4. Save the issued credentials before checking MCP so a temporary verification failure does not lose an otherwise recoverable connection. Reconnect with a fresh transport after completing OAuth; do not restart an already-started transport.

If an email sign-in link opens another browser profile, have the customer restart Connect in that browser rather than weakening session binding.

Discover tools and make this free call using the customer's connection:

{
  "name": "research_credit_quote",
  "arguments": {
    "items": [{ "kind": "search", "operation": "keyword_ideas", "preset": "standard", "quantity": 1 }]
  }
}

An actual successful quote establishes authenticated tool access, even if sufficientBalance is false. Check the MCP isError flag and validate the returned quote before marking the free check successful. A completed OAuth page, visible tool names, or HTTP 200 alone is insufficient. The quote includes availableCredits, totalCredits, totalMaximumHoldCredits, and sufficientBalance.

It does not consume research credits and does not verify upstream paid research providers. Do not run paid research during installation or connection verification.

Status, refresh, and reconnect#

Show disconnected, connected but unverified, verified, reconnect required, and disconnect pending states as appropriate. Use the last successful authenticated check timestamp; do not imply that a stored status is a new live check.

Store access and refresh tokens encrypted server-side against the customer connection. Keep encryption keys in the product's existing secret management system, separately from the database. Keep tokens out of logs, URLs, prompts, browser storage, bundles, analytics, and model-visible tool arguments. Preserve SDK fields such as issuer when saving tokens or registration data.

Refresh before expiration and persist the rotated token set atomically. Serialize refresh, reconnect, and disconnect for each connection across every worker or server instance using the database or an existing distributed lock. Do not rely on an in-process mutex in a multi-instance product.

On invalid_grant, revoked access, or irrecoverable authorization errors, stop using the connection and show "Reconnect required". Background tasks must not initiate interactive consent or silently register a new product client. Transient network failures should preserve credentials and allow a bounded retry.

One connection per account per product#

Dativue currently replaces the previous grant when the same Dativue account reconnects through the same product client. Tell customers that reconnecting replaces their earlier connection to this product, including a connection made in another customer workspace with that same Dativue account. Do not promise independent workspace grants for the same account and product client. Do not work around this behavior by registering a new client for each workspace.

Keep customer records isolated even when an earlier grant is replaced; never copy one customer's credentials into another customer's connection. If the product lets workspaces share one connection, require explicit authorization through its existing access model. Do not change Dativue's grant replacement behavior as part of implementing this guide.

Disconnect#

Require the authenticated administrator and CSRF protection. Immediately disable local tool access and invalidate outstanding connection attempts. Revoke the refresh token using the discovered RFC 7009 revocation_endpoint and the client's registered authentication method, then remove local credentials. Dativue currently advertises /token as that endpoint; revoking a refresh token revokes its grant.

If upstream revocation fails, keep the connection disabled and retain only the encrypted data necessary to retry revocation. Report disconnect pending rather than claiming revocation succeeded. The customer can also revoke the product from their Dativue account.