Know who is signed in

Tokay can identify a Person or Machine before a request reaches your app. Your code receives stable identity and complete matching Group slugs without handling Tokay credentials.

Last updated

AI agent? Start with llms.txt.

Read identity from request headers

Header Value
X-Tokay-Actor-Type PERSON, MACHINE, or SERVICE
X-Tokay-Actor-Id Stable ID of the app Person, Machine, or calling Service
X-Tokay-Actor-Email Person email when present
X-Tokay-Actor-Name Display name when present
X-Tokay-Actor-Groups JSON array of every matching Group slug, empty for direct-only admission
X-Tokay-Session-Id Browser realm or OAuth grant session ID when present

Store X-Tokay-Actor-Id beside app records. It is the same ID the Tokay API returns as that AppPerson's, Machine's, or Service's id, so an allow list can name actors by the IDs Tokay shows you. Compare it as an opaque string. A Person ID stays stable when the same email later becomes a Tokay user. Separate Workspaces receive unrelated app Person IDs.

Groups are trusted claims your app may use for its own roles or behavior. Tokay does not define those permissions. A Service receives only the slugs of its own allowed Groups that the visitor belongs to. Claims are complete and never silently truncated.

Trust the proxy boundary

Tokay removes caller supplied X-Tokay-* values and credentials before it decides access. It injects these headers only after successful verification. Your app never receives the Tokay cookie, JWT, refresh token, or Machine secret.

Understand anonymous requests

A Public Service carries no Tokay identity even when a recognizable Tokay credential is present. A public route inside a Private web Service is also always anonymous. Tokay strips its browser, OAuth, and Machine credentials before proxying.

Treat a missing actor header as anonymous.

Recognize calls from your other Services

Services in one Project call each other at their internal address, which never leaves your Workspace and skips sign in. Those requests carry X-Tokay-Actor-Type: SERVICE and the calling Service's id, as the Tokay API returns it, in X-Tokay-Actor-Id, on Public and Private Services alike.

Browser code can inspect its session

Same origin code on a protected Service can fetch /.tokay/access/me.

{
  "authenticated": true,
  "actor": {
    "type": "PERSON",
    "id": "...",
    "email": "you@example.com",
    "name": "Alex",
    "groups": ["finance", "approvers"]
  }
}

actor.id is the same value as X-Tokay-Actor-Id.

No valid browser session returns 200 with {"authenticated": false}. A 503 means Tokay could not check the session. OAuth and Machine bearers do not affect this browser endpoint. Public Services always report unauthenticated.

Programs carry the same actor model

A Machine request uses MACHINE and keeps the same actor ID when credentials rotate. A Person delegated OAuth request uses PERSON plus X-Tokay-OAuth-Grant-Id and X-Tokay-OAuth-Client-Id.

Sign out belongs to the Project

Link to /.tokay/access/sign-out. Tokay shows confirmation and returns the Person to the requested safe path.

Signing out ends browser sessions across every sibling Service in that Project and requires fresh email proof. Other Projects and OAuth delegations remain active. Paths under /.tokay/ belong to Tokay.