Skip to main content
The GET /tokens/:id endpoint retrieves the full metadata record for a specific token in your workspace. You can use this to check a token’s current status, inspect its assigned scopes, or confirm its expiration date. The response never includes the raw secret value — only the token’s metadata. Required scope: tokens:read

​
Path parameters

​
id
string
required
The unique identifier of the token to retrieve. Format: tok_a1b2c3d4e5f6g7h8i9j0k1l2. This is the id field returned when the token was created or listed.

​
Request

curl --request GET \
  --url https://api.tooken.io/v1/tokens/tok_a1b2c3d4e5f6g7h8i9j0k1l2 \
  --header "Authorization: Bearer tok_live_xxxxxxxxxxxxxxxxxxxx"

​
Response

A successful request returns 200 OK with the token’s metadata object.
​
id
string
required
The unique identifier for the token. Format: tok_a1b2c3d4e5f6g7h8i9j0k1l2.
​
name
string
required
The human-readable name assigned to the token.
​
scopes
string[]
required
The list of permission scopes granted to this token.
​
status
string
required
The current state of the token. One of active, expired, or revoked.
​
created_at
string
required
ISO 8601 datetime when the token was created.
​
expires_at
string
ISO 8601 datetime when the token expires. null if the token has no expiration date.
​
last_used_at
string
ISO 8601 datetime of the most recent request authenticated with this token. null if the token has never been used.
​
created_by
string
required
The email address of the workspace member who created the token.

​
Example response

{
  "id": "tok_a1b2c3d4e5f6g7h8i9j0k1l2",
  "name": "CI Deploy Token",
  "scopes": ["tokens:read", "tokens:write"],
  "status": "active",
  "created_at": "2026-01-15T09:00:00Z",
  "expires_at": "2027-01-15T09:00:00Z",
  "last_used_at": "2026-04-27T14:32:00Z",
  "created_by": "alice@example.com"
}

​
Error responses

If the token ID does not exist in your workspace, or was created in a different workspace, the API returns: 
{
  "error": "not_found",
  "message": "Token tok_a1b2c3d4e5f6g7h8i9j0k1l2 not found",
  "status": 404
}
You still receive a 200 OK for tokens that have been revoked or have expired — the status field in the response reflects their current state. The record remains retrievable even after revocation.