Skip to main content
The POST /tokens endpoint creates a new token in your workspace. You define the token’s name, the scopes it can access, and an optional expiration date. On success, the response includes the raw secret token value — this is the only time Tooken returns the secret, so you must store it securely immediately after creation. Required scope: tokens:write

​
Request body

​
name
string
required
A human-readable label for the token. Maximum 100 characters. Must be unique within your workspace — if a token with the same name already exists, the request returns 409 conflict.
​
scopes
string[]
required
An array of permission scopes to grant to the token. At least one scope is required. Available scopes include tokens:read, tokens:write, and tokens:revoke. Granting only the scopes your use case needs is strongly recommended.
​
expires_at
string
An ISO 8601 datetime string specifying when the token should expire (for example, 2027-01-15T09:00:00Z). If you omit this field, the token never expires. Tokens past their expires_at time automatically transition to expired status and can no longer authenticate requests.

​
Request

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 Token",
    "scopes": ["tokens:read", "tokens:write"],
    "expires_at": "2027-01-15T09:00:00Z"
  }'

​
Response

A successful request returns 201 Created with the full token object, including the secret value.
​
id
string
required
The unique identifier for the newly created token. Format: tok_a1b2c3d4e5f6g7h8i9j0k1l2.
​
token
string
required
The raw secret token value. Use this as your Authorization: Bearer credential. This field is only present on creation — Tooken does not store or return the plaintext secret again after this response.
​
name
string
required
The name you assigned to the token.
​
scopes
string[]
required
The list of scopes granted to the token.
​
status
string
required
The initial status of the token. Always active on creation.
​
created_at
string
required
ISO 8601 datetime when the token was created.
​
expires_at
string
ISO 8601 datetime when the token expires, or null if no expiration was set.
​
last_used_at
string
Always null on a newly created token.
​
created_by
string
required
The email address of the workspace member whose API key was used to create this token.

​
Example response

{
  "id": "tok_a1b2c3d4e5f6g7h8i9j0k1l2",
  "token": "tok_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "name": "CI Deploy Token",
  "scopes": ["tokens:read", "tokens:write"],
  "status": "active",
  "created_at": "2026-04-28T10:00:00Z",
  "expires_at": "2027-01-15T09:00:00Z",
  "last_used_at": null,
  "created_by": "alice@example.com"
}
The token field in the response is the only time Tooken returns the plaintext secret. Copy it immediately and store it in a secrets manager or environment variable. Once this response is gone, the secret cannot be retrieved — you would need to revoke the token and create a new one.