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:
Code
The scheme name Bearer is not case sensitive. A key is accepted only by the endpoints listed under
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:
Code
| 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
categoryset tosafety, in the body ofPOST /v1/incidentsor in the query ofGET /v1/incidents/options, is refused with400, the same answer an unknown category gets. POST /v1/incidentstakes anidthat you create as a UUID and reuse on every retry. If you send anexternal_referencewith asourceand anid, a second report with the same pair creates nothing and answers200with the first incident. A first report answers201.- The
cases.incident-readerscope cannot report an incident. It is refused with403. - 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:
Code
| 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.