Skip to main content
A token is a credential string that Tooken issues to a service or user so it can authenticate downstream API calls on your behalf. Rather than sharing your personal API key everywhere, you create purpose-built tokens with only the permissions they need — and revoke or expire them independently without affecting anything else.

​
What a token is

When you call the Tooken API to create a token, Tooken returns a signed credential string. Any service that holds this string can present it as a Bearer token to authenticate requests. Tokens are not your Tooken dashboard API key — they are distinct credentials you manage through Tooken.
The raw token string (token field) is shown only once at creation time. Tooken does not store it in recoverable form after that. Copy it to a secure secrets manager before closing the response.

​
Token anatomy

Every token Tooken issues is represented as a JSON object. Here is a complete example:
token object
{
  "id": "tok_a1b2c3d4e5f6g7h8i9j0k1l2",
  "name": "ci-deploy-bot",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scopes": ["tokens:read", "tokens:rotate"],
  "status": "active",
  "created_at": "2024-03-15T10:00:00Z",
  "expires_at": "2025-03-15T10:00:00Z",
  "last_used_at": "2024-06-01T14:32:11Z",
  "created_by": "user_abc123"
}
FieldDescription
idUnique, stable identifier for this token. Format: tok_xxxxxxxxxxxxxxxxxxxxxxxx. Use this ID to revoke, rotate, or look up the token later.
nameHuman-readable label you assign at creation. Helps you identify the token in dashboards and audit logs.
tokenThe raw credential string the holder presents in requests. Shown once at creation and never again.
scopesArray of permission strings that determine what this token can do. See Token scopes and access control.
statusCurrent lifecycle state: active, expired, or revoked.
created_atISO 8601 timestamp of when the token was issued.
expires_atISO 8601 timestamp after which the token becomes invalid. null if you did not set an expiration.
last_used_atTimestamp of the most recent authenticated request made with this token. Useful for detecting stale credentials.
created_byThe user ID of the Tooken account member who created the token.

​
Token vs. API key

Tooken uses two distinct credential types. Understanding the difference prevents confusion:

Token

A scoped, optionally time-limited credential you create through the Tooken API or dashboard. Issue one per service or integration. Revoke or rotate individually. Format: tok_xxxxxxxxxxxxxxxxxxxxxxxx.

API key

Your personal Tooken dashboard key. Use it to authenticate calls to the Tooken management API itself — for example, to create or revoke tokens. Format: tok_live_xxxxxxxxxxxxxxxxxxxx. Guard this carefully; do not distribute it.
In practice: your API key creates and manages tokens. Tokens authenticate your end services. Never use your API key where a token belongs.

​
Token lifecycle

A token moves through a defined set of states from the moment you create it:
1

Created

You call POST https://api.tooken.io/v1/tokens. Tooken returns the token object including the one-time-visible token string. Status is active.
2

Active

The token is valid. Any holder can authenticate requests within the token’s scopes. Tooken updates last_used_at on each successful use.
3

Expired or revoked

The token is no longer valid. An expired token passed its expires_at timestamp. A revoked token was explicitly invalidated via POST /tokens/:id/revoke. Both states return a 401 Unauthorized on use.

​
Token statuses

StatusMeaningHow it happens
activeToken is valid and can authenticate requestsDefault state after creation
expiredToken passed its expires_at timestampAutomatic, based on the expiration you set
revokedToken was explicitly invalidatedYou or a team member called the revoke endpoint
Once a token is revoked or expired, Tooken does not restore it. Create a new token if you need to re-issue access.

​
Creating a token

1

Authenticate with your API key

Include your Tooken API key as a Bearer token in the Authorization header of every management request.
2

POST to the tokens endpoint

Send a request with the token name, scopes, and optional expiration.
curl --request POST \
  --url https://api.tooken.io/v1/tokens \
  --header 'Authorization: Bearer tok_live_xxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "ci-deploy-bot",
    "scopes": ["tokens:read", "tokens:rotate"],
    "expires_at": "2025-03-15T10:00:00Z"
  }'
3

Store the token value securely

Copy the token field from the response into your secrets manager, CI environment variables, or vault. You will not be able to retrieve it again from Tooken.

​
Best practices

Follow these practices to keep your token inventory clean and your attack surface small:
  • One token per service. Issue a dedicated token for each integration, pipeline, or service account. If one is compromised, you revoke only that credential.
  • Name tokens descriptively. Use names like github-actions-deploy or analytics-reader so you can immediately identify the owner from audit logs.
  • Always set an expiration. Tokens without an expires_at are valid indefinitely. Set short-lived expiration for automated pipelines and longer windows only for stable, low-risk integrations. See Token expiration and rotation policies.
  • Grant minimum required scopes. Attach only the scopes a service actually needs. See Token scopes and access control.
  • Audit regularly. Review last_used_at in the Tooken dashboard and revoke tokens that have not been used recently.