Assistant

Redeem a link token

Redeems a link token and creates the grant, binding the channel identity the token carries to the authenticated account. The identity is read from the token server-side — nothing in this request can point the link at a different one. The token is the idempotency key: it is single-use, so a replay of this request fails rather than creating a second grant.

post/v1/assistant/link

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/assistant/link
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Request body

tokenstring required

The single-use token from the link the Assistant sent on the channel.

Example request

{
  "token": "alt_9f8e7d6c5b4a39281706"
}

Response

Grant created. The Assistant answers that identity from the next message on.

idstring required

Public grant ID (agr_ prefix).

channel'discord' | 'whatsapp' | 'slack' required

The channel the linked identity lives on. The app is never a value here: a signed-in web session already is the identity, so it needs no grant.

identifierstring required

The channel identity as an address identifier (discord:dm:<user_id>, whatsapp:dm:<phone>), the one grammar channels use on the wire. One identity operates one account.

display_namestring nullable required

The identity as its channel reported it, when it reported one — what a person recognizes instead of an opaque id. Null when the channel offers nothing better than the identifier.

scopesAssistantScope[] required

What the Assistant may do on the account. Deliberately coarse: the consent for a specific dangerous action is asked for when it happens, through the approval queue, rather than pre-granted here.

status'active' | 'revoked' required

Whether the Assistant currently answers this identity.

last_used_atstring date-time nullable required

When the Assistant last acted under this grant; null if never.

created_atstring date-time required

Example response

{
  "id": "agr_V1StGXR8Z5jdHi6B",
  "channel": "discord",
  "identifier": "discord:dm:112233445566778899",
  "display_name": "ana",
  "scopes": [
    "read"
  ],
  "status": "active",
  "last_used_at": "2026-07-17T09:12:00.000Z",
  "created_at": "2026-07-17T00:00:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.