Skip to main content

Connect a signed-in person's account to their actor

By the end of this tutorial you will have a multi-user app whose agents call X with each signed-in person's own account, proven by a tool call that returns that person's X profile.

Five steps:

  1. Sign the person in.
  2. Find or create their actor.
  3. Connect their account, only when it is not connected.
  4. Call a tool as that actor.
  5. Serve the tool to their own AI client.

Every call is shown for all three clients. The ids in the responses are examples — copy the ones your own calls return.

This is the other way round from Sign your users in with a provider, where naturali's connection is the login. Here your app already signs people in, and the connection only carries the tool scopes.

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 whose scopes are the ones your tools need, such as tweet.read, tweet.write and offline.access, with its redirect registered at X (Redirect URI):

    export OAUTH_CLIENT=oauc_V1StGXR8Z5jdHi6B
  3. An http tool that calls X as the actor, built as in Call the provider as the actor:

    export TOOL=tool_V1StGXR8Z5jdHi6B

1. Sign the person in​

Use your own auth library for this (for example @ttoss/oauth-client) and ask X for the minimum scope, such as users.read: the login only has to tell you which X account the person is. Nothing here is a naturali call.

Keep the provider's stable account id from the login, never the email or the username, which a person can change. Prefix it with the provider so ids from two providers never collide:

export SUBJECT=x:2244994945
warning

X invalidates a person's earlier tokens when they authorize again. That only ends the login token from this step, which you use once to read the account id, so discard it. The tool grant in step 3 is a separate authorization held by naturali.

2. Find or create their actor​

Creating an actor is idempotent on external_id: a new person answers 201, a returning one answers 200 with the same actor every time.

naturali create-actor --name Ana --external-id "$SUBJECT"
{ "id": "actor_V1StGXR8Z5jdHi6B", "name": "Ana", "external_id": "x:2244994945" }
export ACTOR=actor_V1StGXR8Z5jdHi6B

3. Connect their account, only when it is not connected​

Read the actor's connection through your OAuth client first.

naturali list-oauth-connections --actor-id "$ACTOR" --oauth-client-id "$OAUTH_CLIENT"
{ "data": [], "next_cursor": null }

When no connection is connected, start one and send the person to authorize_url. A returning person whose connection is pending or disconnected is re-authorized on the same connection (200), never duplicated.

naturali create-oauth-connection \
--oauth-client-id "$OAUTH_CLIENT" \
--actor-id "$ACTOR" \
--return-url https://app.example.com/settings/connections
{
"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"
}

After consent the browser returns to your return_url with oauth_connection_id and status. Anyone can type that URL, so read the connection again and require connected before you rely on it.

warning

Start the connection on the person's own actor from step 2, never on a provisional actor that you move to their external_id later: whoever consents at authorize_url connects their account to the actor it was started for, and a moved actor leaves a window where the grant belongs to nobody you identified.

4. Call a tool as that actor​

Call the tool directly with the actor's id, which makes it send that actor's token.

naturali call-tool --tool-id "$TOOL" --actor-id "$ACTOR"
{ "data": { "id": "2244994945", "name": "Ana", "username": "ana_dev" } }

data.id is the id in your external_id: the tool ran as that person. A session opened with actor_id runs the agent's tools the same way.

5. Serve the tool to their own AI client​

An MCP server lets the person's own AI client call the tool. Point its auth at an authorization server that MCP clients can use (for example @ttoss/auth-core, or Auth0, WorkOS, Stytch or Clerk), so your app writes no OAuth server of its own. naturali checks every token against the server's jwks_uri, and context_claims copies a claim of the token, here the actor id your authorization server puts in it, into the call's context.

naturali create-mcp-server \
--name my-x \
--tools "[{ \"tool_id\": \"$TOOL\", \"name\": \"get-my-x-profile\" }]" \
--auth '{ "type": "oauth", "issuer": "https://login.example.com", "jwks_uri": "https://login.example.com/.well-known/jwks.json", "context_claims": { "person_actor": "actor_id" } }'
{
"id": "mcps_V1StGXR8Z5jdHi6B",
"name": "my-x",
"url": "https://mcp.naturali.ai/servers/mcps_V1StGXR8Z5jdHi6B"
}
warning

The authorization server must sign tokens asymmetrically (RS256, ES256 or EdDSA) and publish its keys at jwks_uri over https; its tokens' aud must be the server's url.

Validation​

Step 4 is the proof: the tool answered with the signed-in person's own X profile. A second sign-in by the same person returns the same actor in step 2 and skips step 3 while the connection stays connected.

What's next​