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.
- In the Scannable web app, open Settings → API keys.
- Select Create API key, and give the key a name and an optional description.
- Choose an expiry: 7, 30, 60 or 90 days, a custom date, or never.
- Tick Read for each resource the integration needs.
- 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.
| Scope | Grants |
|---|---|
members:read | Read the members of your organisation. |
teams:read | Read teams and their members. |
folders:read | Read your folders and their permissions. |
items:read | Read your items, their data fields and history, and your labels. |
inspections:read | Read inspections, with their checklist results and attachments. |
checklists:read | Read your checklists and their criteria. |
inspection-frequencies:read | Read 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.
curl https://api.scannable.io/v1/auth/me \
-H "Authorization: Bearer $SCANNABLE_API_KEY"{
"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"]
}| Field | Meaning |
|---|---|
type | equipment_owner for this API. A key from a manufacturer organisation reads manufacturer. |
member_id | The member who created the key. It is null once they have left the organisation. |
user | Always null for an API key, which acts for the organisation rather than a person. |
scopes | What 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
| Status | code | Cause | What to do |
|---|---|---|---|
401 | unauthorized | The 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. |
403 | forbidden_scope | The key lacks a scope the endpoint needs. details.required lists the missing scopes. | Create a key with those scopes. |
403 | forbidden_scope | The key has no scopes at all. | Create a key with the scopes you need. |
403 | forbidden_scope | The key belongs to a manufacturer organisation. hint says so. | Use the manufacturer API, or a key from your equipment owner organisation. |
{
"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
Authorizationheader. 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.