Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.toktra.dev/llms.txt

Use this file to discover all available pages before exploring further.

The Toktra API supports two authentication methods: OAuth 2.0 client credentials for applications that need scoped, short-lived access, and API keys for simpler server-to-server integrations.

​
OAuth 2.0

OAuth 2.0 with the client_credentials grant is the recommended method. It issues short-lived tokens that expire automatically, reducing the blast radius if a token is ever leaked.
1

Create an OAuth client

In the Toktra dashboard, go to Developer → OAuth Clients and click New client. Give it a descriptive name (e.g., ci-pipeline or data-export-service) and save. You will receive a client_id and client_secret — copy the secret now, as it will not be shown again.
2

Exchange credentials for an access token

POST to /v1/oauth/token with grant_type=client_credentials and your client credentials in the request body.
curl -X POST https://api.toktra.io/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
The response contains your access token:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}
3

Use the token

Include the token in the Authorization header on every API request:
curl https://api.toktra.io/v1/usage \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Token expiry

Access tokens expire after 3,600 seconds (1 hour) by default. When a token expires, the API returns 401 Unauthorized with "error": "unauthorized". Your application should request a new token and retry the request.
Implement proactive token refresh by caching the token and requesting a new one a minute or two before expires_in elapses, rather than waiting for a 401.

​
Managing OAuth clients

You can create, list, and revoke OAuth clients programmatically via the /v1/oauth/clients endpoints. 
curl https://api.toktra.io/v1/oauth/clients \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
API keys

API keys are long-lived credentials suited for simple server-to-server integrations where managing token refresh is unnecessary. To create an API key, go to Developer → API Keys in the Toktra dashboard and click New API key. Copy the key immediately — it is shown only once. Pass the API key directly as a Bearer token: 
curl https://api.toktra.io/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"
API keys do not expire automatically. Treat them like passwords — store them in a secrets manager and never commit them to source control.

​
Security best practices

  • One client per integration. Create a separate OAuth client or API key for each service or pipeline. This way you can revoke access to a single integration without affecting others.
  • Rotate regularly. Rotate API keys and OAuth client secrets on a regular schedule (e.g., every 90 days) and immediately after any suspected exposure.
  • Use environment variables. Never hardcode credentials. Store them in environment variables or a secrets manager such as AWS Secrets Manager or HashiCorp Vault.
  • Prefer OAuth for user-facing apps. OAuth tokens expire automatically and are easier to scope than long-lived API keys.