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. 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.

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.