# Authenticating with an API key

An API key is a secret that starts with `tlpk_`. It belongs to one customer's integration user and
carries one or more **scopes**. Each scope allows one kind of access.

## Get a key

Ask your ThinkLP contact. Staff issue the key and set its name, its scopes and its expiry date. The
secret is shown to staff once and cannot be shown again, so store it as soon as you receive it. If
you lose it, ask for a new key.

Treat the key like a password. Do not put it in client-side code or in source control.

## Send the key

Send the key as a bearer token in the `Authorization` header of every request:

```bash
curl 'https://api.thinklp.com/v1/integration/check' \
  -H 'Authorization: Bearer tlpk_YOUR_KEY'
```

The scheme name `Bearer` is not case sensitive. A key is accepted only by the endpoints listed under
[Endpoints that accept a key](#endpoints-that-accept-a-key). Any other endpoint answers `401` with the
code `WRONG_APPLICATION`.

## Test the key

`GET /v1/integration/check` confirms that the key works. It needs the `integration.connection-check`
scope and nothing else. A successful call answers `200`:

```json
{
  "data": {
    "tenant_id": "0b6f8a52-3c1e-4c55-9a40-6d2f1e7b9a10",
    "tenant_name": "Acme Retail",
    "user_id": "5d9a0c7e-82b1-4f3a-b6e4-1c2d3e4f5a6b",
    "user_name": "Acme integration",
    "key_name": "Acme production",
    "scopes": ["integration.connection-check"],
    "expires_at": "2027-11-13T00:00:00.000Z"
  }
}
```

| Field                      | Meaning                                        |
| -------------------------- | ---------------------------------------------- |
| `tenant_id`, `tenant_name` | The customer account the key belongs to        |
| `user_id`, `user_name`     | The integration user the API acts as           |
| `key_name`                 | The name staff gave the key                    |
| `scopes`                   | The scope keys the key holds                   |
| `expires_at`               | When the key stops working, as a UTC date-time |

Every success body wraps its result in `data`.

## Scopes

| Scope                          | Label            | Allows                                              | Also needs a team role for the user |
| ------------------------------ | ---------------- | --------------------------------------------------- | ----------------------------------- |
| `integration.connection-check` | Connection check | Call `GET /v1/integration/check`                    | No                                  |
| `cases.incident-writer`        | Incident writer  | Report Loss Prevention incidents and read them back | Yes                                 |
| `cases.incident-reader`        | Incident reader  | Read Loss Prevention incidents                      | Yes                                 |

A key's scopes are fixed when it is issued. To get another scope, ask for a new key.

The two incident scopes depend on the integration user's own permissions in your account. A request
must pass both checks, and either one can refuse it. A key with an incident scope whose user has no
team role that grants the permission is refused with `403 PERMISSION_DENIED`. ThinkLP staff set up the
role when they issue the key. `integration.connection-check` does not depend on the user's
permissions.

## Endpoints that accept a key

| Endpoint                                             | Scope needed                                       | Use it to                                                          |
| ---------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------ |
| `GET /v1/integration/check`                          | `integration.connection-check`                     | Confirm the key works                                              |
| `POST /v1/incidents`                                 | `cases.incident-writer`                            | Report a Loss Prevention incident                                  |
| `GET /v1/incidents/:id`                              | `cases.incident-writer` or `cases.incident-reader` | Read an incident by its id                                         |
| `GET /v1/incidents?external_source=&external_id=`    | `cases.incident-writer` or `cases.incident-reader` | Find an incident by the source system and id you reported it under |
| `GET /v1/incidents/options?category=loss_prevention` | `cases.incident-writer` or `cases.incident-reader` | List the incident types and other choices the customer accepts     |

Notes:

- A key reaches **Loss Prevention** only. A request with `category` set to `safety`, in the body of
  `POST /v1/incidents` or in the query of `GET /v1/incidents/options`, is refused with `400`, the
  same answer an unknown category gets.
- `POST /v1/incidents` takes an `id` that you create as a UUID and reuse on every retry. If you send
  an `external_reference` with a `source` and an `id`, a second report with the same pair creates
  nothing and answers `200` with the first incident. A first report answers `201`.
- The `cases.incident-reader` scope cannot report an incident. It is refused with `403`.
- Every other incident endpoint refuses a key with `401 WRONG_APPLICATION`. That covers drafts,
  extracting details, settings, gate decisions and evidence.

## Errors

An error has this body:

```json
{ "error": { "code": "API_KEY_INVALID", "message": "The API key is not valid." } }
```

| Status | Code                         | What it means                                                                       | What to do                                  |
| ------ | ---------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------- |
| 401    | `AUTH_TOKEN_MISSING`         | The `Authorization` header is missing, or it is not a bearer token                  | Send `Authorization: Bearer <key>`          |
| 401    | `API_KEY_INVALID`            | The key is unknown, revoked or expired, or its integration user is no longer active | Ask your ThinkLP contact for a new key      |
| 401    | `WRONG_APPLICATION`          | The endpoint does not accept API keys                                               | Use an endpoint that lists API keys         |
| 403    | `PERMISSION_DENIED`          | The key does not hold a scope that allows this endpoint                             | Ask for a key with the scope                |
| 403    | `FRONTLINE_CHANNEL_MISMATCH` | The key's user is not an integration user                                           | Ask your ThinkLP contact to check the key   |
| 503    | `AUTH_SERVER_UNAVAILABLE`    | The key could not be checked right now                                              | Retry shortly. The request was not accepted |

`API_KEY_INVALID` has one message for every cause, so the response does not tell you which one it
was.

## Expiry and revocation

A key stops working at its `expires_at` time. Staff can also revoke a key, or deactivate its
integration user, at any time. The API checks the key on every request and keeps no copy of the
answer, so a revoked key is refused on its next request.

To replace a key before it expires, ask for a second key, switch your system to it, and then ask
ThinkLP staff to revoke the first. Both keys work until the first is revoked.
