Skip to main content
Every request to the Tooken API must be authenticated. Tooken uses two distinct credential types for different purposes: API keys authenticate requests you make to manage Tooken itself, while tokens are the credentials Tooken issues for use in your own systems and integrations. Understanding the difference between them helps you choose the right credential for each use case.

​
API keys vs. tokens

API keysTokens
PurposeManage Tooken (create tokens, view audit logs, configure settings)Authenticate downstream services and integrations
Issued byThe Tooken dashboardThe Tooken API or dashboard
ScopedNo — full workspace accessYes — limited to assigned scopes
RotatableYes, from Settings → API KeysYes, via the API
Use inYour server-side code and CI/CD pipelinesServices, partners, and integrations that consume your API
Use your API key when you’re calling Tooken’s API to manage credentials. Use tokens when you’re issuing credentials for external services or internal systems to authenticate with your own APIs.

​
Pass your API key in requests

Include your API key as a Bearer token in the Authorization header of every request to https://api.tooken.io/v1. 
curl --request GET \
  --url https://api.tooken.io/v1/tokens \
  --header 'Authorization: Bearer tok_live_xxxxxxxxxxxxxxxxxxxx'
Store your API key in an environment variable named TOOKEN_API_KEY and read it at runtime. Never hardcode credentials in source files — even in private repositories, secrets committed to version control are difficult to fully remove and easy to leak.

​
Authentication errors

If your API key is missing, malformed, or has been revoked, the API returns a 401 Unauthorized response: 
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
Common causes of a 401 response:
  • The Authorization header is absent from the request.
  • The key value has extra whitespace or is malformed — confirm the header reads exactly Bearer tok_live_xxxxxxxxxxxxxxxxxxxx with a single space after Bearer.
  • The API key has been regenerated or deleted in the dashboard, invalidating the old value.
A 403 Forbidden response indicates your credentials are valid but the token lacks the required scope for the requested operation. Check the scopes assigned to the token and update them if needed.

​
Rotate your API key

If your API key is compromised, or as part of routine credential hygiene, you can regenerate it from the dashboard:
  1. Open app.tooken.io and navigate to Settings → API Keys.
  2. Find the key you want to rotate and click Regenerate.
  3. Copy the new key value immediately — it is displayed only once.
  4. Update the key in every environment and service that uses it.
Regenerating an API key immediately and permanently invalidates the old key. Any service still using the old value will begin receiving 401 errors as soon as you regenerate. Update all consumers before or immediately after rotating.
You can also delete an API key entirely from the same Settings page. Deletion has the same effect as regeneration — the old key stops working immediately — but does not produce a replacement value.

​
Security recommendations

  • Use environment variables — read TOOKEN_API_KEY at runtime rather than embedding the value in code or configuration files checked into source control.
  • Scope tokens narrowly — when issuing tokens for downstream services, assign only the scopes that service needs. A token with tokens:read cannot create or revoke tokens even if your API key can.
  • Set expiration dates — tokens without an expiration remain valid indefinitely. For machine credentials, set a short expires_at and rotate on a schedule.
  • Audit regularly — review the audit log in Settings → Audit Log to confirm that API keys and tokens are being used as expected and to detect unexpected access patterns early.