# Authentication

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

1. Sign in to the [dashboard](https://turnix.io/app) and select the project.
2. Open [API Tokens](https://turnix.io/app/project/tokens) and click **Create new API Token**.
3. Enter a name (for example `production-backend`) and copy the token.

> **Warning: 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](https://turnix.io/app/project/tokens).

> **Danger: 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

**cURL**

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

**Node.js**

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

**Python**

```python
import os, requests

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