Skip to main content

OAuth Connections

One actor's grant at a provider through an OAuth client. SOAT runs the authorization code flow, keeps the tokens encrypted, refreshes them, and an http tool with auth.type: oauth_connection calls the provider as the actor the turn runs for.

Overview​

  1. POST /api/v1/oauth-connections with the client and the actor returns an authorize_url.
  2. Send the person to it. They consent at the provider, which redirects to the callback with code and state.
  3. GET /api/v1/oauth-connections/callback exchanges the code and the connection becomes connected.
  4. In a session for that actor, or called directly with its actor_id, an http tool with auth: { "type": "oauth_connection", "oauth_client_id": "oauc_…" } sends Authorization: Bearer <the actor's access token>.

Tokens are write-only: no route returns them.

See the Permissions Reference for the IAM action strings for this module.

Data Model​

FieldTypeDescription
idstringPublic identifier (e.g. ocon_…)
project_idstringID of the owning project
oauth_client_idstringThe OAuth client it connects through
actor_idstringThe actor the grant is for
statusstringpending, connected or disconnected
scopesstring[]Scopes the provider granted
expires_atstring | nullWhen the current access token expires
connected_atstring | nullWhen the last authorization completed
errorobject | null{ code, message } of the last failed authorization or refresh
created_atstringISO 8601 creation timestamp
updated_atstringISO 8601 last-updated timestamp

POST /api/v1/oauth-connections also returns authorize_url and authorize_url_expires_at.

Key Concepts​

One connection per actor and client​

Starting again for the same actor and client restarts the same connection (200 instead of 201), with a new authorize_url. A connected connection keeps its tokens until the new authorization completes.

The authorization​

  • state is random, single-use and expires after 10 minutes; a replayed, unknown or expired one is 400 OAUTH_CALLBACK_FAILED.
  • PKCE S256 is used unless the client sets pkce: false.
  • A refused consent (error=access_denied) or a code the token endpoint refuses is 400 OAUTH_CALLBACK_FAILED, and an unconnected connection becomes disconnected with the error.
  • With return_url, the callback redirects there instead, adding oauth_connection_id and status (connected or failed) to its query.

Whoever consents at the authorize_url connects their account to the actor it was started for: hand it only to that person.

Using a connection from a tool​

The tool sends the token of the connection held by the call's actor: the actor in the turn's tool_context, which the server pins, or the actor_id of a direct POST /api/v1/tools/{tool_id}/call, which must be an actor of the calling project. A caller never names the actor through tool_context. Each call needs oauth-connections:UseOauthConnection on the connection (srn:<project_id>:oauth_connection:<oauth_connection_id>) from the caller and, in a turn, the agent's policy_ids; ${iam:ActorId} in a policy condition binds to the turn's actor. A refusal reaches the model as the tool's result, the denial body, or answers the direct call with 403, and nothing is sent.

A call with no actor is 502 TOOL_AUTH_FAILED. An actor with no connected connection (none made, disconnected, or its refresh refused) is 409 OAUTH_CONNECTION_REQUIRED, telling the actor to reconnect; error meta carries oauth_client_id, actor_id and, when one exists, oauth_connection_id, the ids a client needs to start the connection again. In a turn the model reads it as the tool's error.

Refresh​

An access token within 60 seconds of expires_at is refreshed before it is sent. Refreshes take a per-connection lock, so concurrent calls refresh once: providers such as X rotate the refresh token on every use, and a second refresh with the old one would be refused. A refresh the provider refuses (4xx) sets the connection disconnected with OAUTH_CONNECTION_REFRESH_FAILED and answers the call 409 OAUTH_CONNECTION_REQUIRED; a provider that cannot answer (5xx, network) fails only that call, 502 TOOL_AUTH_FAILED.

Deletion​

DELETE /api/v1/oauth-connections/{oauth_connection_id} revokes the refresh token (else the access token) at the client's revocation_url, then deletes; a failed revocation does not stop the deletion. Deleting the actor or the OAuth client deletes its connections.

Configuration​

Environment VariableRequiredDescription
SECRETS_ENCRYPTION_KEYYesEncrypts the stored tokens and PKCE verifiers, as it does secrets.
SOAT_BASE_URLNoBuilds the default callback {SOAT_BASE_URL}/api/v1/oauth-connections/callback for a client with no redirect_uri.

Examples​

Start a connection​

soat create-oauth-connection --oauth-client-id oauc_01 --actor-id actor_01 \
--return-url https://app.example.com/settings/connections

Call the provider as the actor​

soat create-tool --project-id proj_ABC --name get-my-x-profile --type http \
--execute '{"url": "https://api.x.com/2/users/me", "method": "GET", "auth": {"type": "oauth_connection", "oauth_client_id": "oauc_01"}}'

Call the provider as the actor without a session​

soat call-tool --tool-id tool_01 --actor-id actor_01