Skip to main content

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.

ConcernOwner
The authorization flow, PKCE and state, exchanging the codenaturali
Storing, refreshing and revoking tokens; no route returns themnaturali
Calling the provider as the actor, from an agent turn or a direct callnaturali
Reading the provider account, finding or creating the user, deduplicating a second loginyour application
Your own session cookie and logoutyour application
Provisional actors: creating one before consent, deleting it when unusedyour application

Seven steps:

  1. Create the profile tool.
  2. Create a provisional actor.
  3. Start the connection.
  4. Confirm the connection on return.
  5. Read who consented.
  6. Find or create the user.
  7. 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​

  1. A credential. A nat_sk_… API key exported as NATURALI_TOKEN, and your client set up — the CLI, the SDK or plain curl. 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 only
    export PROJECT=proj_V1StGXR8Z5jdHi6B
    export NATURALI_PROJECT_ID=$PROJECT # lets the CLI omit --project-id
  2. An OAuth client for X with the users.read scope, its redirect registered at X as https://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.

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\"}}"
{ "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.

naturali create-actor --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.

naturali create-oauth-connection \
--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.

naturali get-oauth-connection --oauth-connection-id "$CONNECTION"
{ "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.

naturali call-tool --tool-id "$TOOL" --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.

naturali list-actors --external-id "$SUBJECT"
{ "data": [], "next_cursor": null }

No match: a new user. The provisional actor becomes the user's actor.

naturali update-actor --actor-id "$PROVISIONAL" --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.

naturali delete-actor --actor-id "$PROVISIONAL"
warning

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​