Machines and credentials

Machines let scripts, CI jobs, integrations, and AI tools call a protected app without pretending to be a person. A Machine is a durable identity for one Project. Its credentials rotate independently and its access history stays attached to the Machine.

Last updated

AI agent? Start with llms.txt.

A Machine credential opens your deployed app. It cannot manage Tokay Services, code, or settings. Platform credentials are covered in For AI agents.

Create one identity per caller

Machines live on the Project's Access tab. Create a Machine with a descriptive name such as billing-worker or production-ci. Creating it emits no secret.

A Project can have up to 100 active Machines. Removing a Machine ends the identity and revokes every credential it holds.

Issue credentials separately

Issue one or more named credentials from the Machine row. Each full value looks like tokay_machine_<key_id>_<secret> and appears once. Store it in the caller's secret manager before closing the dialog. Tokay stores only a verifier and cannot show the secret again.

Each Machine can have up to 100 active credentials. Use separate credentials when callers need independent rotation, attribution, or revocation.

Send it with each request

curl -H "Authorization: Bearer tokay_machine_..." https://my-api-r4k7x2m9.tokay.app/report

Tokay authenticates the request before it reaches your app. The Project access log records the stable Machine identity and the specific credential presented.

Rotate without replacing the identity

Issue a new credential, update the caller, confirm it works, then revoke the old credential. Revoking one credential leaves the Machine, its history, and its other credentials active. An active Project usually receives the change in about 10 seconds. An idle Project can take up to five minutes. If Tokay authentication is unavailable, cached Machine credentials can remain usable for up to 48 hours before Tokay fails closed.

If one caller should no longer exist, remove the Machine instead. Revocation and removal cannot be undone.