Skip to main content

OAuth Clients

Your own OAuth 2.0 apps at third-party providers (X, Google, GitHub, …), which actors connect their accounts through with OAuth connections.

Overview​

An OAuth client belongs to a project and holds what the provider issued when you registered the app: its endpoints, client_id and a secret reference to its client secret. The app is yours: its name is the one on the provider's consent screen, and provider verifications (such as Google's restricted scopes) are yours to obtain.

This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → OAuth Clients.

Data Model​

OauthClient​

FieldTypeDescription
idstring
project_idstring
namestring
authorize_urlstringThe provider's authorization endpoint. Query parameters it already carries are kept.
token_urlstringThe provider's token endpoint.
revocation_urlstring, nullableThe provider's RFC 7009 revocation endpoint, called when a connection is deleted. null skips revocation.
client_idstringYour app's client ID at the provider.
client_secretstring, nullableA {{secret:sec_...}} reference to your app's client secret, never the value. null for a public client, which relies on PKCE.
scopesstring[]The scopes requested at authorization.
pkcebooleanWhether the authorization uses PKCE (S256).
token_endpoint_auth_methodclient_secret_basic | client_secret_postHow the client authenticates at the token endpoint.
redirect_uristring, nullableThe callback the provider redirects to, as registered with the provider. Absent on create, or null, it is this API's own https://api.naturali.ai/v1/oauth/callback, the URL to register with the provider; a front end that receives the redirect itself forwards code and state there.
authorize_paramsobject, nullableExtra query parameters for the authorize URL, such as Google's access_type: offline and prompt: consent for a refresh token.
created_atstring (date-time)
updated_atstring (date-time)

Key Concepts​

Set up the app at the provider​

  1. Register an OAuth 2.0 app in the provider's developer console.
  2. Add https://api.naturali.ai/v1/oauth/callback as its redirect (callback) URI.
  3. Request the scopes the tools you plan to call need; for a refresh token, add the provider's offline scope (X: offline.access) or its authorize parameters (Google: { "access_type": "offline", "prompt": "consent" } in authorize_params).
  4. Store the client secret as a secret and create the client here with {{secret:sec_…}} as client_secret. A public client (PKCE only) has none.

The client secret is a reference​

client_secret takes only a secret reference; a literal is 400. The reference is what a read returns. A key narrowed by capabilities to oauth-clients:CreateOauthClient or oauth-clients:UpdateOauthClient may reference the project's secrets in it.

Redirect URI​

redirect_uri is the callback the provider sends the person back to. Omitted on a create, or set to null, it is https://api.naturali.ai/v1/oauth/callback, which completes the connection and is the URI to register with the provider; a read returns it. A front end of your own that receives the provider's redirect (your domain on the consent screen) sets its own URI here and forwards code and state to that callback. The same holds on every path that writes a client: a formation oauth_client resource and an agent's tool call.

Deletion​

Deleting a client deletes every connection made through it, without revoking them at the provider; delete the connections first to revoke.

Examples​

Create a client for X​

naturali create-oauth-client \
--project-id proj_V1StGXR8Z5jdHi6B \
--name x \
--authorize-url https://x.com/i/oauth2/authorize \
--token-url https://api.x.com/2/oauth2/token \
--revocation-url https://api.x.com/2/oauth2/revoke \
--client-id Tm9ZWdEX2hQ \
--client-secret '{{secret:sec_V1StGXR8Z5jdHi6B}}' \
--scopes '["tweet.read","users.read","offline.access"]'

The answer's redirect_uri is https://api.naturali.ai/v1/oauth/callback.