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
POST /api/v1/oauth-connectionswith the client and the actor returns anauthorize_url.- Send the person to it. They consent at the provider, which redirects to the callback with
codeandstate. GET /api/v1/oauth-connections/callbackexchanges the code and the connection becomesconnected.- In a session for that actor, or called directly with its
actor_id, anhttptool withauth: { "type": "oauth_connection", "oauth_client_id": "oauc_…" }sendsAuthorization: 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
| Field | Type | Description |
|---|---|---|
id | string | Public identifier (e.g. ocon_…) |
project_id | string | ID of the owning project |
oauth_client_id | string | The OAuth client it connects through |
actor_id | string | The actor the grant is for |
status | string | pending, connected or disconnected |
scopes | string[] | Scopes the provider granted |
expires_at | string | null | When the current access token expires |
connected_at | string | null | When the last authorization completed |
error | object | null | { code, message } of the last failed authorization or refresh |
created_at | string | ISO 8601 creation timestamp |
updated_at | string | ISO 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
stateis random, single-use and expires after 10 minutes; a replayed, unknown or expired one is400 OAUTH_CALLBACK_FAILED.- PKCE
S256is used unless the client setspkce: false. - A refused consent (
error=access_denied) or a code the token endpoint refuses is400 OAUTH_CALLBACK_FAILED, and an unconnected connection becomesdisconnectedwith theerror. - With
return_url, the callback redirects there instead, addingoauth_connection_idandstatus(connectedorfailed) 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 Variable | Required | Description |
|---|---|---|
SECRETS_ENCRYPTION_KEY | Yes | Encrypts the stored tokens and PKCE verifiers, as it does secrets. |
SOAT_BASE_URL | No | Builds the default callback {SOAT_BASE_URL}/api/v1/oauth-connections/callback for a client with no redirect_uri. |
Examples
Start a connection
- CLI
- SDK
- curl
soat create-oauth-connection --oauth-client-id oauc_01 --actor-id actor_01 \
--return-url https://app.example.com/settings/connections
const { data, error } = await soat.oauthConnections.createOauthConnection({
body: {
oauth_client_id: 'oauc_01',
actor_id: 'actor_01',
return_url: 'https://app.example.com/settings/connections',
},
});
if (error) throw new Error(JSON.stringify(error));
// Send the person to data.authorize_url
curl -X POST https://api.example.com/api/v1/oauth-connections \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"oauth_client_id": "oauc_01", "actor_id": "actor_01", "return_url": "https://app.example.com/settings/connections"}'
Call the provider as the actor
- CLI
- SDK
- curl
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"}}'
const { data, error } = await soat.tools.createTool({
body: {
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' },
},
},
});
if (error) throw new Error(JSON.stringify(error));
curl -X POST https://api.example.com/api/v1/tools \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"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
- CLI
- SDK
- curl
soat call-tool --tool-id tool_01 --actor-id actor_01
const { data, error } = await soat.tools.callTool({
path: { tool_id: 'tool_01' },
body: { actor_id: 'actor_01' },
});
if (error) throw new Error(JSON.stringify(error));
curl -X POST https://api.example.com/api/v1/tools/tool_01/call \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"actor_id": "actor_01"}'