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.