Sign your users in with a provider
By the end of this tutorial you will have a "Sign in with X" flow that maps each X account to one actor, proven by a second login with the same account finding the same actor.
An OAuth connection is delegated authorization, not authentication: naturali holds the grant and calls the provider as the actor, and your application decides who the user is.
| Concern | Owner |
|---|---|
The authorization flow, PKCE and state, exchanging the code | naturali |
| Storing, refreshing and revoking tokens; no route returns them | naturali |
| Calling the provider as the actor, from an agent turn or a direct call | naturali |
| Reading the provider account, finding or creating the user, deduplicating a second login | your application |
| Your own session cookie and logout | your application |
| Provisional actors: creating one before consent, deleting it when unused | your application |
Seven steps:
- Create the profile tool.
- Create a provisional actor.
- Start the connection.
- Confirm the connection on return.
- Read who consented.
- Find or create the user.
- Prove it: sign in again.
Every call is shown for all three clients. The ids in the responses are examples — copy the ones your own calls return.
Prerequisites
-
A credential. A
nat_sk_…API key exported asNATURALI_TOKEN, and your client set up — the CLI, the SDK or plaincurl. Calls run on your backend; the key never reaches the browser.export NATURALI_TOKEN=nat_sk_...export NATURALI_API=https://api.naturali.ai/v1 # curl examples onlyexport PROJECT=proj_V1StGXR8Z5jdHi6Bexport NATURALI_PROJECT_ID=$PROJECT # lets the CLI omit --project-id -
An OAuth client for X with the
users.readscope, its redirect registered at X ashttps://api.naturali.ai/v1/oauth/callback(Redirect URI):export OAUTH_CLIENT=oauc_V1StGXR8Z5jdHi6B
1. Create the profile tool
Once per project: an http tool that reads the X account
of whichever actor it runs for.
- CLI
- SDK
- curl
naturali create-tool \
--name get-x-profile \
--type http \
--execute "{\"url\":\"https://api.x.com/2/users/me\",\"method\":\"GET\",\"auth\":{\"type\":\"oauth_connection\",\"oauth_client_id\":\"$OAUTH_CLIENT\"}}"
const { data: tool } = await naturali.tools.createTool({
path: { project_id: process.env.PROJECT! },
body: {
name: 'get-x-profile',
type: 'http',
execute: {
url: 'https://api.x.com/2/users/me',
method: 'GET',
auth: {
type: 'oauth_connection',
oauth_client_id: process.env.OAUTH_CLIENT!,
},
},
},
});
curl -X POST "$NATURALI_API/projects/$PROJECT/tools" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"name\": \"get-x-profile\",
\"type\": \"http\",
\"execute\": {
\"url\": \"https://api.x.com/2/users/me\",
\"method\": \"GET\",
\"auth\": { \"type\": \"oauth_connection\", \"oauth_client_id\": \"$OAUTH_CLIENT\" }
}
}"
{ "id": "tool_V1StGXR8Z5jdHi6B", "name": "get-x-profile", "type": "http" }
export TOOL=tool_V1StGXR8Z5jdHi6B
2. Create a provisional actor
Before consent you do not know who the user is, so every login starts with an
actor that holds no external_id yet.
- CLI
- SDK
- curl
naturali create-actor --name pending-login
const { data: provisional } = await naturali.actors.createActor({
path: { project_id: process.env.PROJECT! },
body: { name: 'pending-login' },
});
curl -X POST "$NATURALI_API/projects/$PROJECT/actors" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "pending-login" }'
{ "id": "actor_K8vQzL2mN4pR7sT9", "name": "pending-login", "external_id": null }
export PROVISIONAL=actor_K8vQzL2mN4pR7sT9
3. Start the connection
return_url is your backend's login callback. Keep the returned connection id
in a signed, short-lived cookie, then redirect the browser to authorize_url.
- CLI
- SDK
- curl
naturali create-oauth-connection \
--oauth-client-id "$OAUTH_CLIENT" \
--actor-id "$PROVISIONAL" \
--return-url https://app.example.com/auth/x/return
const { data: started } = await naturali.oauthConnections.createOauthConnection(
{
path: { project_id: process.env.PROJECT! },
body: {
oauth_client_id: process.env.OAUTH_CLIENT!,
actor_id: provisional!.id,
return_url: 'https://app.example.com/auth/x/return',
},
}
);
// Set a signed cookie with started.id, then redirect to started.authorize_url
curl -X POST "$NATURALI_API/projects/$PROJECT/oauth-connections" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"oauth_client_id\": \"$OAUTH_CLIENT\",
\"actor_id\": \"$PROVISIONAL\",
\"return_url\": \"https://app.example.com/auth/x/return\"
}"
{
"id": "ocon_V1StGXR8Z5jdHi6B",
"status": "pending",
"authorize_url": "https://x.com/i/oauth2/authorize?response_type=code&client_id=…&state=…",
"authorize_url_expires_at": "2026-11-11T10:10:00.000Z"
}
export CONNECTION=ocon_V1StGXR8Z5jdHi6B
4. Confirm the connection on return
After consent the browser lands on
https://app.example.com/auth/x/return?oauth_connection_id=ocon_…&status=connected.
Anyone can type that URL: check that oauth_connection_id matches your cookie,
then read the connection and require connected.
- CLI
- SDK
- curl
naturali get-oauth-connection --oauth-connection-id "$CONNECTION"
const { data: connection } =
await naturali.oauthConnections.getOauthConnection({
path: {
project_id: process.env.PROJECT!,
oauth_connection_id: cookieConnectionId,
},
});
if (connection?.status !== 'connected') throw new Error('login not completed');
curl "$NATURALI_API/projects/$PROJECT/oauth-connections/$CONNECTION" \
-H "Authorization: Bearer $NATURALI_TOKEN"
{ "id": "ocon_V1StGXR8Z5jdHi6B", "actor_id": "actor_K8vQzL2mN4pR7sT9", "status": "connected" }
5. Read who consented
Call the tool directly for the
provisional actor: actor_id makes it send that actor's token, with no agent
and no generation.
- CLI
- SDK
- curl
naturali call-tool --tool-id "$TOOL" --actor-id "$PROVISIONAL"
const { data: me } = await naturali.tools.callTool({
path: { project_id: process.env.PROJECT!, tool_id: process.env.TOOL! },
body: { actor_id: connection!.actor_id },
});
curl -X POST "$NATURALI_API/projects/$PROJECT/tools/$TOOL/call" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d "{ \"actor_id\": \"$PROVISIONAL\" }"
{ "data": { "id": "2244994945", "name": "Ana", "username": "ana_dev" } }
data.id is the account's stable id at X; the username can change. Prefix it
with the provider so ids from two providers never collide:
export SUBJECT=x:2244994945
6. Find or create the user
Look the account up by external_id.
- CLI
- SDK
- curl
naturali list-actors --external-id "$SUBJECT"
const { data: found } = await naturali.actors.listActors({
path: { project_id: process.env.PROJECT! },
query: { external_id: `x:${me.data.id}` },
});
curl "$NATURALI_API/projects/$PROJECT/actors?external_id=$SUBJECT" \
-H "Authorization: Bearer $NATURALI_TOKEN"
{ "data": [], "next_cursor": null }
No match: a new user. The provisional actor becomes the user's actor.
- CLI
- SDK
- curl
naturali update-actor --actor-id "$PROVISIONAL" --name Ana --external-id "$SUBJECT"
await naturali.actors.updateActor({
path: { project_id: process.env.PROJECT!, actor_id: provisional!.id },
body: { name: me.data.name, external_id: `x:${me.data.id}` },
});
curl -X PATCH "$NATURALI_API/projects/$PROJECT/actors/$PROVISIONAL" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d "{ \"name\": \"Ana\", \"external_id\": \"$SUBJECT\" }"
export ACTOR=$PROVISIONAL
A match: a returning user. Use the actor found and delete the provisional one, which deletes its connection.
- CLI
- SDK
- curl
naturali delete-actor --actor-id "$PROVISIONAL"
await naturali.actors.deleteActor({
path: { project_id: process.env.PROJECT!, actor_id: provisional!.id },
});
curl -X DELETE "$NATURALI_API/projects/$PROJECT/actors/$PROVISIONAL" \
-H "Authorization: Bearer $NATURALI_TOKEN"
Deleting the provisional connection revokes its token at X. Before relying on
the returning user's own connection, list it with
GET /v1/projects/{project_id}/oauth-connections
and actor_id, and check it is still connected; if it is disconnected,
start a connection for that actor (step 3), which asks the user to consent
again.
Either way, issue your own session cookie for the resolved actor. Its id is what
your app passes as actor_id from then on: in
sessions, and in direct calls such as a daily sync of
the user's posts.
Delete provisional actors whose login never returned (external_id still
null after the authorize_url expired); naturali does not clean them up.
7. Prove it: sign in again
Run steps 2 to 6 again with the same X account. Step 6 now finds one actor:
{
"data": [{ "id": "actor_K8vQzL2mN4pR7sT9", "name": "Ana", "external_id": "x:2244994945" }],
"next_cursor": null
}
The second login resolved to the actor of the first; you deleted the second provisional actor.
What's next
- Recognise one user across a channel and your app — the same actor on WhatsApp and in your app.
- OAuth Connections — refresh, deletion and the callback.
- Tools — direct calls and
tool_context.