Authentication · API reference · Docs

The Turnix API uses API tokens sent as Bearer tokens:

http

Authorization: Bearer YOUR_API_TOKEN

API tokens#

Each token belongs to one project in your organization. Credentials you request with it, and their traffic, are recorded in that project.
A token works for all API endpoints of its project. There are no finer-grained permissions or scopes to choose.
Tokens do not expire. They stay valid until you remove them.

Create a token#

Sign in to the dashboard and select the project.
Open API Tokens and click Create new API Token.
Enter a name (for example production-backend) and copy the token.

The token is shown only once

After you close the dialog, the token cannot be displayed again. If you lose it, create a new one.

Store and use it safely#

Keep the token on your server, for example in an environment variable (TURNIX_API_TOKEN) or a secrets manager.
Never put it in browser JavaScript, mobile apps, desktop apps or public repositories. Anyone who has it can create credentials and relay traffic billed to you.
Do not log full Authorization headers.
Use separate tokens (and ideally separate projects) for staging and production, so you can replace one without touching the other.

Rotate or remove a token#

To rotate, create a new token, deploy it, then remove the old one under API Tokens.

Use Remove, not Revoke, after a leak

To cut off a leaked token for certain, click Remove. Removing deletes the token, and every request that uses it fails with 401 Token not found.

Errors#

Status	Body	Cause
`401`	`{"error":"Not Authorized","code":"unauthorized"}`	No `Authorization` header, or it does not use the `Bearer` scheme
`401`	`{"error":"Token not found","code":"unauthorized"}`	The token does not exist (typo, or it was removed)
`401`	`{"error":"You are not on any subscription","code":401}`	The organization has no active plan

Example#

bash

curl https://turnix.io/api/v1/regions \
  -H "Authorization: Bearer $TURNIX_API_TOKEN"

javascript

const res = await fetch("https://turnix.io/api/v1/regions", {
  headers: { Authorization: `Bearer ${process.env.TURNIX_API_TOKEN}` },
});

python

import os, requests

res = requests.get(
    "https://turnix.io/api/v1/regions",
    headers={"Authorization": f"Bearer {os.environ['TURNIX_API_TOKEN']}"},
    timeout=10,
)