Machines and credentials
Machines let scripts, jobs, integrations, and AI tools call a protected app as themselves. A Machine has one durable Project identity while its credentials and where it is allowed change independently. A Machine calls your app, and a Bot works in Tokay itself, so an agent that deploys and inspects your Project needs a Bot, and one that calls the running app needs a Machine.
Last updated
AI agent? Start with llms.txt.
Create one identity per caller
Machines live on the Machines tab of the Workspace Access page, and each has its own page. Create a descriptive Machine such as billing_worker or production_ci. In the app, New Machine names the Machine and issues its first credential in one step, and New Machine on any service's Access tab or Group page creates one that is allowed there right away. Through the API, createMachine emits no secret and issueMachineCredential mints one. An AI agent on Tokay MCP calls both through mutate_platform_graphql with the PROJECT_WRITE permission its connection holds by default. Issuing and revokeMachineCredential confirm first: the first call returns CONFIRMATION_REQUIRED with a token in extensions.confirmation, and repeating the call with confirmationToken added to the input runs it.
A Project can have up to 100 active Machines. Deleting one ends its identity and revokes every credential it holds.
Admit the Machine
A Machine reaches an app when a Private Service allows it directly or through one of the Project's Groups. Creating a Machine alone does not admit it anywhere.
The same Machine may be allowed on several Services directly or through a reused Group. Tokay sends the complete matching Group slugs with each admitted request. Direct-only admission sends an empty list.
Issue credentials separately
Each named credential appears once as tokay_machine_<key_id>_<secret>, on a page you leave only after saving it. Tokay stores only a verifier and cannot show it again.
curl -H "Authorization: Bearer tokay_machine_..." https://my-api-r4k7x2m9.tokay.app/report
Tokay verifies both the credential and current Service admission before user code runs. A credential that is malformed or revoked gets 401 with error: "invalid_token". A valid credential whose Machine the Service doesn't allow gets 403 with error: "insufficient_scope" and an error_description naming the Machine and its Project, so the fix is to allow it there, or to use the right Project's Machine, rather than to replace the credential.
A caller can ask which Machine it is: GET /.tokay/access/me with the same Authorization header answers {"authenticated":true,"actor":{"type":"MACHINE","id":"…","name":"…","groups":[…]}}, the identity the app receives in its X-Tokay-Actor-* headers. Through the API, a Machine's name is machine.name.
Rotate without changing identity
Issue a new credential from the Machine's page, update the caller, confirm it works, then revoke the old credential. The Machine ID, where it is allowed, and its access history stay intact.
Public and Private changes, who is allowed, Groups, credentials, and removals take effect through fast access state. If the Auth state feed is unavailable, the standard plan can use last known authority for up to 24 hours before failing closed.