Server tokens

A publishable key identifies an agent. It sits inside your app and in your web page, so anyone can read it. Server tokens close that gap: your server — which knows who signed in — mints a short-lived token for one user of one agent with your secret API key, and the SDK sends it with everything it asks of Graine. Once the agent requires them, a request without a valid token for that agent and that user is refused.

Requires SDK 0.14.4 (iOS, Android, Kotlin Multiplatform, Flutter) or React Native 0.47.3, and website loader 1.5.0.

Server tokens are the strongest of the three ways to prove who your users are, and the one we recommend for sensitive data such as health or money. To compare them with your sign-in's ID token and a signed user ID, see Which way should you prove users?

1. Turn on Report only

In the dashboard, open the agent → Embed & Widgets → Install → Server tokens, and choose Report only. Nothing is refused yet; every request is counted by what its token said — valid, missing, expired, for another agent — so you can see when every build of your app sends one. Each check is also a row in the agent's Security log; while you are report-only, a request without a valid token says Would be refused.

2. Mint tokens on your server

From your own backend, with your secret API key (Settings → API keys). Mint when your user signs in and whenever the SDK asks for a fresh one; never put the API key in an app or a page.

curl https://api.graine.ai/v2/client-tokens \
  -H "Authorization: Bearer $GRAINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_0123",
    "user_id": "cust-42",
    "scopes": ["chat", "call", "memory", "booking"],
    "ttl_seconds": 900
  }'

{
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9.eyJpc3MiOiJncmFpbmUiLCJhdWQiOiJncmFpbmUtZW1iZWQiLCJzdWIiOiJjdXN0LTQyIn0.c2lnbmF0dXJl",
  "expires_at": "2026-10-27T10:15:00Z",
  "expires_in": 900,
  "agent_id": "agt_0123",
  "scopes": ["chat", "call", "memory", "booking"]
}

• user_id is your user's identifier in the field the agent's Who is the user? setting names — exactly what your app passes to identify().
• ttl_seconds is 60 to 3600 (default 3600). A token carries no personal data beyond the user id.
• The key needs the calls:write scope. An agent of another workspace answers 404.

3. Give the SDK a token provider

The provider is called when the SDK starts, again shortly before each token expires (in the background, at a slightly different moment on each device), and when Graine refuses a token. Return null when no token can be had right now — the SDK tries again later. Fetch it from your own server, which mints only for the user its sign-in proved.

Graine.configure(
    GraineConfig(
        baseUrl = "https://www.graine.ai",
        publishableKey = "pk_live_…",
        tokenProvider = { myApi.graineToken() },   // suspend () -> String?
    )
)

4. Enforce

When Report only shows valid tokens and nothing missing for a few days, choose Enforce. The dashboard states the effect and asks you to confirm.

Scopes

A token covers only what you minted it for. A missing scope refuses that action only: a token without memory still chats and calls, but cannot read what the agent remembers.

Past sessions need chat or call. Loading the agent's settings needs any valid token.

When a token is refused

The error arrives as each SDK's error type, with the code and a reason (agent, user or scope for token_scope).