ThinkLP
Guides

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:

TerminalCode
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. 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:

JSONCode
{ "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" } }
FieldMeaning
tenant_id, tenant_nameThe customer account the key belongs to
user_id, user_nameThe integration user the API acts as
key_nameThe name staff gave the key
scopesThe scope keys the key holds
expires_atWhen the key stops working, as a UTC date-time

Every success body wraps its result in data.

Scopes

ScopeLabelAllowsAlso needs a team role for the user
integration.connection-checkConnection checkCall GET /v1/integration/checkNo
cases.incident-writerIncident writerReport Loss Prevention incidents and read them backYes
cases.incident-readerIncident readerRead Loss Prevention incidentsYes

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

EndpointScope neededUse it to
GET /v1/integration/checkintegration.connection-checkConfirm the key works
POST /v1/incidentscases.incident-writerReport a Loss Prevention incident
GET /v1/incidents/:idcases.incident-writer or cases.incident-readerRead an incident by its id
GET /v1/incidents?external_source=&external_id=cases.incident-writer or cases.incident-readerFind an incident by the source system and id you reported it under
GET /v1/incidents/options?category=loss_preventioncases.incident-writer or cases.incident-readerList 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:

JSONCode
{ "error": { "code": "API_KEY_INVALID", "message": "The API key is not valid." } }
StatusCodeWhat it meansWhat to do
401AUTH_TOKEN_MISSINGThe Authorization header is missing, or it is not a bearer tokenSend Authorization: Bearer <key>
401API_KEY_INVALIDThe key is unknown, revoked or expired, or its integration user is no longer activeAsk your ThinkLP contact for a new key
401WRONG_APPLICATIONThe endpoint does not accept API keysUse an endpoint that lists API keys
403PERMISSION_DENIEDThe key does not hold a scope that allows this endpointAsk for a key with the scope
403FRONTLINE_CHANNEL_MISMATCHThe key's user is not an integration userAsk your ThinkLP contact to check the key
503AUTH_SERVER_UNAVAILABLEThe key could not be checked right nowRetry 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.

Last modified on