Skip to main content
The Tooken REST API gives you full programmatic control over your tokens, scopes, and audit data. Every feature available in the Tooken dashboard is also available through the API, so you can integrate token lifecycle management directly into your own tooling, CI/CD pipelines, or internal applications.

​
Base URL

All API requests go to: 
https://api.tooken.io/v1
Every endpoint path shown in this documentation is relative to this base URL.

​
Authentication

Authenticate by passing your API key in the Authorization header as a Bearer token: 
Authorization: Bearer tok_live_xxxxxxxxxxxxxxxxxxxx
You can generate API keys from the Settings → API Keys section of your Tooken workspace. Keep your keys secret — treat them with the same care as passwords. If a key is compromised, revoke it immediately from the dashboard.
Never expose your API key in client-side code, public repositories, or logs. All requests must be made server-side.

​
Request and response format

All request bodies must be sent as JSON with the appropriate content type header: 
Content-Type: application/json
All responses are returned as JSON. Successful responses include the requested resource or a list of resources. Error responses follow a consistent format — see the errors reference for details.

​
Rate limiting

The API enforces a limit of 1,000 requests per minute per workspace. Every response includes the following headers so you can track your usage:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed per minute
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp (seconds) when the limit resets
When X-RateLimit-Remaining reaches 0, subsequent requests return 429 Too Many Requests. Wait until the time indicated by X-RateLimit-Reset before retrying.
Build retry logic that checks X-RateLimit-Remaining before sending a request and backs off automatically when the value is low, rather than waiting for a 429 response.

​
Pagination

Endpoints that return collections are paginated. Every list response follows this shape: 
{
  "data": [...],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 100
  }
}
Control pagination with query parameters:
ParameterDefaultMaximumDescription
page1—Page number to retrieve
per_page25100Number of items per page
For example, to retrieve the second page with 50 results per page: 
GET /tokens?page=2&per_page=50

​
Versioning

The current API version is v1, indicated in the URL path. When Tooken introduces breaking changes, a new version is released at a new path (e.g., /v2). The old version remains available for a deprecation period communicated in advance. You can safely build against v1 without unexpected breaking changes.

​
Example requests

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