Authentication

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.

Sending the token

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

curl https://api.tolk.every-day.io/v1/project \
  -H "Authorization: Bearer $TOLK_TOKEN" \
  -H "Accept: application/json"

use Illuminate\Support\Facades\Http;

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

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();

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
`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.

​Sending the token

​Scopes

​Error codes

​Rate limit

​Storing tokens

Sending the token

Scopes

Error codes

Rate limit

Storing tokens