Skip to main content

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​

  1. POST /v1/projects/{project_id}/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 their browser to https://api.naturali.ai/v1/oauth/callback with code and state.
  3. The 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 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​

FieldTypeDescription
idstring
project_idstring
oauth_client_idstring
actor_idstring
statuspending | connected | disconnectedpending until the first authorization completes; connected while tool calls can use it; disconnected after a refused authorization or refresh, until the actor connects again.
scopesstring[]The scopes the provider granted.
expires_atstring (date-time), nullableWhen the current access token expires; it is refreshed before use.
connected_atstring (date-time), nullable
errorobject, nullableWhy the last authorization or refresh failed.
created_atstring (date-time)
updated_atstring (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, a 302 to it, with oauth_connection_id and status (connected or failed) 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 is 400.

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​

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

Call the provider as the actor​

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"}}'

Call the provider directly as an actor​

naturali call-tool \
--project-id proj_V1StGXR8Z5jdHi6B \
--tool-id tool_V1StGXR8Z5jdHi6B \
--actor-id actor_V1StGXR8Z5jdHi6B