Skip to main content
This guide walks you through everything you need to go from a blank slate to issuing and using your first Tooken token. By the end, you’ll have a workspace, an API key, a scoped token, and a working API call.
1

Sign up and create a workspace

Go to app.tooken.io and create your account. After signing in, you’ll be prompted to create your first workspace.Workspaces are isolated environments — all tokens, API keys, audit logs, and settings live inside a workspace. Give your workspace a name that reflects its purpose, such as production or my-team.
Create separate workspaces for production and staging environments so credentials never cross between them.
2

Get your API key

Inside your workspace, navigate to Settings → API Keys and click Create API Key. Give it a descriptive name — for example, local-dev or ci-pipeline — and click Create.Your new API key looks like this:
tok_live_xxxxxxxxxxxxxxxxxxxx
Copy your API key now and store it somewhere safe — such as a password manager or secrets manager. Tooken does not display the full key value again after you leave this page.
You’ll use this key to authenticate all requests to the Tooken API. Keep it out of source control and never share it in plaintext.
3

Create your first token

With your API key in hand, send a POST request to /v1/tokens to create a scoped token. The example below creates a token named my-first-token with the tokens:read scope.
curl --request POST \
  --url https://api.tooken.io/v1/tokens \
  --header 'Authorization: Bearer tok_live_xxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "my-first-token",
    "scopes": ["tokens:read"]
  }'
A successful response returns the new token along with its metadata:
{
  "id": "tkn_01hzq8p3vkdxyz1234567890ab",
  "token": "tok_live_abcdefghijklmnopqrstuvwxyz",
  "name": "my-first-token",
  "scopes": ["tokens:read"],
  "created_at": "2026-04-28T10:00:00Z",
  "expires_at": null
}
The token value in the response is shown only once. Copy it immediately and store it securely before closing the response. If you lose it, you’ll need to create a new token — Tooken cannot retrieve the value again.
The expires_at field is null when no expiration is set. To issue a token that expires automatically, include an "expires_at" field in your request with an ISO 8601 timestamp.
4

Use your token

Pass the token value you received as a Bearer token in the Authorization header of any downstream request that requires it.
curl --request GET \
  --url https://api.tooken.io/v1/tokens \
  --header 'Authorization: Bearer tok_live_abcdefghijklmnopqrstuvwxyz'
Because the token was created with the tokens:read scope, it can list and retrieve token records but cannot create or revoke them. If a request requires a scope the token doesn’t have, the API returns a 403 Forbidden response.

​
Next steps

Authentication

Learn the difference between API keys and tokens, and how to handle auth errors.

Scopes

Explore all available scopes and how to combine them for least-privilege access.

Expiration policies

Set expiration dates and configure automatic rotation for long-lived tokens.

API reference

Browse every endpoint in the Tooken REST API.