> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolk.every-day.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Every request uses a project token as a bearer token.

The API uses project tokens. A token belongs to one project and can only access that project. A manager creates it under **Settings › API tokens** (*Instellingen › API-tokens*); see [API tokens](/guide/api-tokens).

## Sending the token

Send the token in the `Authorization` header, always over HTTPS:

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.tolk.every-day.io/v1/project \
    -H "Authorization: Bearer $TOLK_TOKEN" \
    -H "Accept: application/json"
  ```

  ```php PHP (Laravel) theme={null}
  use Illuminate\Support\Facades\Http;

  $project = Http::withToken(env('TOLK_TOKEN'))
      ->acceptJson()
      ->get('https://api.tolk.every-day.io/v1/project')
      ->throw()
      ->json('data');
  ```

  ```javascript Node theme={null}
  const response = await fetch('https://api.tolk.every-day.io/v1/project', {
    headers: {
      Authorization: `Bearer ${process.env.TOLK_TOKEN}`,
      Accept: 'application/json',
    },
  });
  const { data: project } = await response.json();
  ```
</CodeGroup>

The project follows from the token: there is no project in the URL, and a `?project=` parameter is ignored.

## Scopes

| Scope | Endpoints |
| - | - |
| `read` | `GET /project`, `GET /stats`, `GET /keys`, `GET /translations/{locale}`, `GET /exports/{profileKey}`, `GET /jobs/{jobId}` |
| `write` | `PATCH /keys/{keyHash}`, `POST /keys/diff`, `POST /keys/sync`, `PUT /translations/{locale}`, `POST /imports` |

A token always has `read`, and optionally `write`. In CI that only fetches, use a token with only `read`.

## Error codes

| Code | Meaning |
| - | - |
| `401` | No token, or an unknown, expired or revoked token. Also when the project or the customer has been deleted |
| `403` | The token lacks the scope of the endpoint, or the project is archived. Once the project is restored, the token works again |
| `422` with `reason: key_limit_reached` | A sync would take the customer over the key limit of its plan; see [Key limit](/developers/syncing-keys#key-limit) |
| `429` | Too many requests. Wait the number of seconds in the `Retry-After` header |

## Rate limit

Two limits apply:

* **Per token:** 120 requests per minute. Every response has the headers `X-RateLimit-Limit` and `X-RateLimit-Remaining`.
* **Per IP address:** 600 requests per minute, counted before the token is checked, so also for requests with an invalid token. That is five tokens at full speed behind one address, for example a CI runner behind NAT.

Above a limit, the response is `429` with `Retry-After` (seconds), as JSON.

## Storing tokens

* Locally in `.env` as `TOLK_TOKEN`, never in git.
* In GitHub as the repository or organization secret `TOLK_TOKEN`.
* A token starts with `tolk_`, so secret scanning recognizes it if it ends up somewhere anyway.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.