Scannable Docs
Get started

Authentication

Send an API key with every request, and choose the scopes it grants.

Every request carries an API key as a bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

An API key acts for your organisation, not for the person who created it. It sees every folder and item in your organisation, whatever folder permissions say.

Create a key

Only organisation admins can create, see and revoke API keys.

  1. In the Scannable web app, open Settings → API keys.
  2. Select Create API key, and give the key a name and an optional description.
  3. Choose an expiry: 7, 30, 60 or 90 days, a custom date, or never.
  4. Tick Read for each resource the integration needs.
  5. Create the key and copy it. Scannable shows it once, so store it in your secrets manager straight away.

If you can't see the tab, you aren't an admin. Ask one of your organisation's admins to create the key.

Use one key per system, such as one for your asset register and one for a test environment. You can then revoke one without breaking the others.

Scopes

A scope grants read access to one group of resources. A request needs the scope its endpoint lists. A key with no scopes is refused by every endpoint.

ScopeGrants
members:readRead the members of your organisation.
teams:readRead teams and their members.
folders:readRead your folders and their permissions.
items:readRead your items, their data fields and history, and your labels.
inspections:readRead inspections, with their checklist results and attachments.
checklists:readRead your checklists and their criteria.
inspection-frequencies:readRead your inspection frequencies.

A member is anyone in your organisation, whatever their role. It is not the same as the Member role, which a member's role shows as member. A member keeps one member_… identifier in every team they belong to. To find someone's identifier, filter the members list by email.

Check a key

Get the authenticated identity returns the organisation the key acts for and the scopes it grants. Any key with at least one scope can call it.

Request
curl https://api.scannable.io/v1/auth/me \
  -H "Authorization: Bearer $SCANNABLE_API_KEY"
Response
{
  "organisation_id": "org_8r4lvh6r3knlg1w",
  "type": "equipment_owner",
  "member_id": "member_tsyqfxifv1te4qf",
  "name": "Southern Alps Rope Access",
  "created_at": "2024-05-13T08:00:00.000Z",
  "auth_method": "api_key",
  "user": null,
  "roles": [],
  "scopes": ["items:read", "folders:read", "inspections:read"]
}
FieldMeaning
typeequipment_owner for this API. A key from a manufacturer organisation reads manufacturer.
member_idThe member who created the key. It is null once they have left the organisation.
userAlways null for an API key, which acts for the organisation rather than a person.
scopesWhat the key grants. Read it to predict a 403.

You can't add scopes to an existing key. Create a new key with the scopes you need, switch your integration to it, then revoke the old one.

When a request is refused

StatuscodeCauseWhat to do
401unauthorizedThe header is missing or malformed, or the key is invalid, expired or revoked.Check the header format. Create a new key if this one expired.
403forbidden_scopeThe key lacks a scope the endpoint needs. details.required lists the missing scopes.Create a key with those scopes.
403forbidden_scopeThe key has no scopes at all.Create a key with the scopes you need.
403forbidden_scopeThe key belongs to a manufacturer organisation. hint says so.Use the manufacturer API, or a key from your equipment owner organisation.
403 for a missing scope
{
  "error": {
    "code": "forbidden_scope",
    "message": "Missing required scope.",
    "details": { "required": ["inspections:read"] },
    "request_id": "req_01j9x4m2k7qv3n8r5t6w0y1z2a"
  }
}

See Errors for the full error envelope.

Keep keys safe

  • Send keys only in the Authorization header. Never put a key in a URL or query string, where logs and proxies record it.
  • Keep keys out of source control and client-side code.
  • Revoke a key in Settings → API keys as soon as you suspect it has leaked. Revoking takes effect straight away and can't be undone.

On this page