Authentication

Public API v1 uses HTTP Bearer authentication with self-serve API keys. There is no query-string, cookie, or X-Api-Key header auth.

Create an API key

1. Sign in at Toksta.
2. Open Account → API keys (direct link: /account#api-keys).
3. Confirm you have an active dedicated API or SaaS plan with API access enabled.
4. Click Create key, give it a descriptive name, and optionally restrict endpoint scopes.
5. Copy the full secret immediately — it is shown once at creation. Toksta stores only a SHA-256 hash; the secret cannot be recovered later.

Keys are prefixed tk_live_ followed by 48 hex characters (example shape: tk_live_a1b2c3d4…).

For step-by-step UI guidance, see Managing API Keys.

Send the key on every request

Authorization: Bearer tk_live_<your-secret>
Content-Type: application/json

Example with curl:

curl -sS https://api.toksta.com/v1/account/usage \
  -H "Authorization: Bearer tk_live_YOUR_SECRET_HERE"

Always call the API from your backend. Never expose keys in client-side JavaScript, mobile apps, or public repositories.

Rotate a key

Rotation creates a new secret, marks the old key as revoked, and shows the new secret once — same rules as creation. Update your integration before deleting the old secret from your secrets manager.

Revoke a key

Revoked keys immediately return 401 UNAUTHORIZED. Revoke keys you no longer use or that may have been exposed.

Scope restrictions

When creating a key, you can limit which endpoint families it may call. A scoped key that hits a disallowed route returns 403 FORBIDDEN.

Security checklist

• Store keys in a secrets manager (not in source control).
• Use separate keys per integration or service (do not reuse one key everywhere).
• Rotate keys on a schedule or after team member offboarding.
• Monitor usage via GET /v1/account/usage and your server logs.

Troubleshooting

Symptom	Likely cause
401 UNAUTHORIZED	Missing Bearer prefix, wrong key, revoked key, or typo
403 FORBIDDEN	Free plan, past-due billing, API access disabled, or key scope too narrow
Key not visible after creation	Secrets are one-time reveal only — rotate to get a new secret