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
| Field | Type | Description |
|---|---|---|
id | string | |
project_id | string | |
name | string | |
authorize_url | string | The provider's authorization endpoint. Query parameters it already carries are kept. |
token_url | string | The provider's token endpoint. |
revocation_url | string, nullable | The provider's RFC 7009 revocation endpoint, called when a connection is deleted. null skips revocation. |
client_id | string | Your app's client ID at the provider. |
client_secret | string, nullable | A {{secret:sec_...}} reference to your app's client secret, never the value. null for a public client, which relies on PKCE. |
scopes | string[] | The scopes requested at authorization. |
pkce | boolean | Whether the authorization uses PKCE (S256). |
token_endpoint_auth_method | client_secret_basic | client_secret_post | How the client authenticates at the token endpoint. |
redirect_uri | string, nullable | The 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_params | object, nullable | Extra query parameters for the authorize URL, such as Google's access_type: offline and prompt: consent for a refresh token. |
created_at | string (date-time) | |
updated_at | string (date-time) |
Key Concepts
Set up the app at the provider
- Register an OAuth 2.0 app in the provider's developer console.
- Add
https://api.naturali.ai/v1/oauth/callbackas its redirect (callback) URI. - 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" }inauthorize_params). - Store the client secret as a secret and create the client
here with
{{secret:sec_…}}asclient_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
- CLI
- SDK
- curl
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"]'
const { data: client } = await naturali.oauthClients.createOauthClient({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
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'],
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/oauth-clients \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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.