OAuth Connections
One actor's grant at a provider through an
OAuth client. The runtime runs the authorization code
flow, keeps the tokens encrypted and refreshes them, and an http
tool with auth.type: oauth_connection calls the provider as the
actor the turn runs for, or the actor a direct call names.
Overview
POST /v1/projects/{project_id}/oauth-connectionswith the client and the actor returns anauthorize_url.- Send the person to it. They consent at the provider, which redirects their
browser to
https://api.naturali.ai/v1/oauth/callbackwithcodeandstate. - The callback exchanges the code and the connection becomes
connected. - 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 never leave the runtime: no route returns them.
This module is a verbatim mirror of the runtime, re-rooted under the project in
the path, except for the callback: the provider calls it with no credential
and no project, so it is served at GET /v1/oauth/callback rather than under
the project.
See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → OAuth Connections.
Data Model
OauthConnection
| Field | Type | Description |
|---|---|---|
id | string | |
project_id | string | |
oauth_client_id | string | |
actor_id | string | |
status | pending | connected | disconnected | pending until the first authorization completes; connected while tool calls can use it; disconnected after a refused authorization or refresh, until the actor connects again. |
scopes | string[] | The scopes the provider granted. |
expires_at | string (date-time), nullable | When the current access token expires; it is refreshed before use. |
connected_at | string (date-time), nullable | |
error | object, nullable | Why the last authorization or refresh failed. |
created_at | string (date-time) | |
updated_at | string (date-time) |
POST /v1/projects/{project_id}/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 callback
GET /v1/oauth/callback takes no credential: the single-use state is the
credential. It answers as the runtime does:
- With the connection's
return_url, a302to it, withoauth_connection_idandstatus(connectedorfailed) added to its query. - Without one, the connected connection as JSON.
- A replayed, unknown or expired
state(10 minutes), a refused consent (error=access_denied) or a code the provider refuses is400.
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 a caller cannot repoint at another actor,
or the actor_id of a direct
POST /v1/projects/{project_id}/tools/{tool_id}/call,
which must be an actor of the project (400 ACTOR_NOT_FOUND otherwise). A call
with no actor, or an actor with no connected connection, fails as the tool's
error telling the actor to reconnect.
Signing users in with a provider
A connection is delegated authorization, not authentication: naturali holds
the grant and calls the provider as the actor; it does not say who the user
is. A "Sign in with X" flow keeps that in your application: a provisional
actor per login, the provider account read through a direct call with
actor_id, and the user found or created by the actor's external_id.
Sign your users in with a provider
walks it, with the split of what your application owns.
When your app already signs people in, Connect a signed-in person's account to their actor connects their account to the one actor they already have.
A key narrowed by capabilities uses
a connection through the capability that starts the generation: each one
carries oauth-connections:UseOauthConnection. A narrowed key without one
cannot.
Refresh and deletion
An access token about to expire is refreshed before it is sent. A refresh the
provider refuses sets the connection disconnected.
DELETE /v1/projects/{project_id}/oauth-connections/{oauth_connection_id}
revokes the grant 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.
Examples
Start a connection
- CLI
- SDK
- curl
naturali create-oauth-connection \
--project-id proj_V1StGXR8Z5jdHi6B \
--oauth-client-id oauc_V1StGXR8Z5jdHi6B \
--actor-id actor_V1StGXR8Z5jdHi6B \
--return-url https://app.example.com/settings/connections
const { data: started } = await naturali.oauthConnections.createOauthConnection(
{
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
oauth_client_id: 'oauc_V1StGXR8Z5jdHi6B',
actor_id: 'actor_V1StGXR8Z5jdHi6B',
return_url: 'https://app.example.com/settings/connections',
},
}
);
// Send the person to started.authorize_url
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/oauth-connections \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"oauth_client_id": "oauc_V1StGXR8Z5jdHi6B",
"actor_id": "actor_V1StGXR8Z5jdHi6B",
"return_url": "https://app.example.com/settings/connections"
}'
Call the provider as the actor
- CLI
- SDK
- curl
naturali create-tool \
--project-id proj_V1StGXR8Z5jdHi6B \
--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_V1StGXR8Z5jdHi6B"}}'
const { data: tool } = await naturali.tools.createTool({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
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_V1StGXR8Z5jdHi6B',
},
},
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/tools \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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_V1StGXR8Z5jdHi6B" }
}
}'
Call the provider directly as an actor
- CLI
- SDK
- curl
naturali call-tool \
--project-id proj_V1StGXR8Z5jdHi6B \
--tool-id tool_V1StGXR8Z5jdHi6B \
--actor-id actor_V1StGXR8Z5jdHi6B
const { data: me } = await naturali.tools.callTool({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
tool_id: 'tool_V1StGXR8Z5jdHi6B',
},
body: { actor_id: 'actor_V1StGXR8Z5jdHi6B' },
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/tools/tool_V1StGXR8Z5jdHi6B/call \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "actor_id": "actor_V1StGXR8Z5jdHi6B" }'