Connections

Your backend calls this endpoint and sends the end user to the returned url (the provider's consent page). The link is valid for 10 minutes and can be used only once (only a hash of state is stored); Google links use PKCE. connectors must all belong to the same provider: gmail and calendar belong to google, slack belongs to slack; duplicates are removed.

After the end user consents, the provider redirects to GET /v1/oauth/{provider}/callback; the control plane exchanges the code for tokens and then redirects to return_url. See that endpoint's description. Each (developer, end user, provider) has at most one active connection at a time; authorizing again replaces the old one.

If you have not registered your own OAuth app (PUT /v1/oauth-clients/{provider}) and no platform test app is configured either, 409 no_oauth_client is returned.

Not for developers to call: this is the callback URL you register with Google / Slack (redirect_uri; see GET /v1/oauth-clients). It is public, takes no API key, and accepts only a one-time state.

• Valid state: the code is exchanged for tokens, the account details are fetched and everything is stored encrypted in the credential vault; the response is then a 302 redirect to the return_url given when authorization started, with these appended after any existing query parameters: on success status=ok&connection_id=conn_...; on failure (the user declined at the provider, or the token exchange failed) status=error&error=<reason>. The response carries Cache-Control: no-store. On success a connection.created webhook is sent.
• Missing state, or state expired or already used: there is nowhere to redirect, so a 400 HTML error page is returned (meant for the end user, not JSON).
• Unknown provider: 404.

Newest first, at most 500, not paginated: when there are more, has_more is true; filter by end_user_id to see them. Revoked connections are excluded by default. Tokens are never included in the response.

Makes a best effort to revoke the tokens at the provider too (a failure there does not block the local revocation); locally the encrypted tokens are erased, the placeholder tokens issued to environments are invalidated, the status becomes revoked, and a connection.revoked webhook is sent. Returns the revoked connection (200, not 204). Revoking an already revoked connection returns it unchanged.

One entry per provider (google, slack): the client_id you registered (null if none; the secret is never returned), whether the platform test app is available, and the callback URL redirect_uri (which you must register with the provider).

Once registered, the consent page shows your app's name; otherwise the platform's test app is used (only test users can authorize it). The client secret is stored encrypted and never returned afterwards. A second PUT replaces it. An empty client_id or client_secret gives 400; an unknown provider gives 404.