# Part 1 · The API

## 1.1 Making an API token

**Who** · Whoever may make API tokens (`token.manage`: Admin; the account holder).

**Where** · The menu under your name › **API tokens** (`/me/token`).

**Before you start** · Know what the program needs to do: give it nothing more.

**The steps**
1. **Name**: what it is for ("Payroll sync").
2. **What it may do**: tick each thing; only what you may do yourself here is offered.
3. **Make the token**, then your password.
4. **Copy it now**: the token shows this once and never again. Keep it like a password.

**What the record shows** · The audit log: **API token made** (its name, what it may do, until when); the sign-in log:
**API token made**.

**Who is told** · Nobody.

**What can go wrong**
- *"Choose at least one thing it may do."*
- *"A token may do only what you may do here."* Your roles changed since the page opened.
- *You lost the token.* Revoke it (1.3) and make another.

## 1.2 Calling the API

**Who** · A program holding a token.

**Where** · `https://<the app>/api/v1/…`, with `Authorization: Bearer <token>` and `Accept: application/json`.

**Before you start** · The token, and the document (1.4) for the endpoint.

**The steps**
1. `GET /api/v1/me`: who the token belongs to, its workspace, and what it may do now.
2. `GET /api/v1/person?q=…&per_page=…`: the workspace's people, a page at a time (`data`, `links`, `meta`).
3. For a call that changes something (none published yet), send an `Idempotency-Key`: the same call again within 24
   hours gets the first answer back and does nothing twice.

**What the record shows** · A change made through the API is in the audit log as **API**.

**Who is told** · Nobody.

**What can go wrong** · Every refusal is problem+json: `type`, `title`, `status`, `detail` (and `errors` by field).
- *401 Not signed in.* The token is wrong, revoked, past its day, or its membership was turned off or its workspace
  paused.
- *403.* The token wasn't allowed that, or you no longer may do it yourself: a call needs both.
- *422.* A field is wrong (`errors`), or an `Idempotency-Key` was reused for a different call.
- *429.* Too many calls this minute for this token: wait for `Retry-After` seconds.

## 1.3 Revoking a token

**Who** · The token's maker.

**Where** · **API tokens** › the bin beside the token.

**Before you start** · Nothing.

**The steps**
1. Press the bin, **Revoke it**, then your password if it has been a while. A program using it stops at once.

**What the record shows** · The audit log and the sign-in log: **API token revoked**.

**Who is told** · Nobody.

**What can go wrong**
- *A person left.* Turning their membership off stops their tokens on the next call; no need to revoke each.

## 1.4 Reading the API's document

**Who** · Whoever may make API tokens, and the Service.

**Where** · **API tokens** › **The API's document** (`/docs/api`; `/docs/api.json` for the OpenAPI file).

**Before you start** · Nothing.

**The steps**
1. Each endpoint: what it takes, what it answers, and the error shapes. Try it with your token.

**What the record shows** · Nothing.

**Who is told** · Nobody.

**What can go wrong**
- *403.* You may not make tokens, so the document isn't yours to read.

## 1.5 Setting the API's limits (Service)

**Who** · The Service.

**Where** · Platform settings › **The API** (**API calls**, **A new API token works for**).

**Before you start** · Nothing.

**The steps**
1. Change the figure and save (the password again).

**What the record shows** · The audit log: **Setting changed**.

**Who is told** · Nobody. A token made earlier keeps the day it was made with.

**What can go wrong**
- *"… must be between …"* The figure is outside its range.