API tokens

API tokens are the credentials machines present on the public /v1 API (account, members, plan, runs). A token IS your account on the wire: it reaches exactly what you reach. API reference is every route it opens.

Token structure and hashing

To prevent token leakage and ensure auditability, the platform implements strict cryptographic hygiene:

• Prefix: Every token begins with tor_ (e.g., tor_abc123...), so a leaked one is recognisable in a log or a repository at a glance.
• Hashing at rest: The platform never stores the plaintext token value. Only a secure cryptographic hash of the token is saved in the database. On every request, the API hashes the incoming token and compares it to the stored hash.
• One-time reveal: When you mint a token in the portal, the plaintext value is displayed exactly once. It is impossible to recover or display the token again after the page is closed. If you lose a token, you must revoke it and mint a new one.

---

Token lifecycle management

You can create and manage API tokens on your API keys page (/keys, on the console sidebar rail). The desktop app’s key is listed there too, under Devices, because its token is a tor_ token like any other — see Signing in the desktop app.

Expiry options

When creating a token, you can set a lifetime policy:

• 30 Days: Recommended for short-lived scripts and tasks.
• 90 Days (Default): Standard lifetime for developer machines.
• 1 Year: Suitable for long-lived infrastructure deployments.
• Never: Use with extreme caution. Recommended only if your internal secret rotation policy handles replacement.

The portal tracks the last_used_at timestamp of each token, allowing you to audit which keys are active.

Immediate revocation

If you suspect a token has leaked or is no longer needed, you can revoke it immediately from the portal. Revocation is instantaneous; any subsequent HTTP request using that token will be rejected with a 401 Unauthorized status code.

Safe rotation (Grace periods)

To rotate a production token without causing service interruption, the platform supports a grace-period rotation model:

1. When you select Rotate in the portal, a new replacement token is minted and displayed.
2. The old token enters a 24-hour grace window. During this period, both the old and new tokens are considered valid.
3. You have 24 hours to update your CI/CD configuration, environment variables, or scripts to use the new token.
4. Once the 24-hour grace window expires, the old token is automatically marked as expired and deactivated.
5. If you need to stop the old token immediately, Revoke it from its row — revocation is instantaneous and ends the grace window early.

---