API Access Tokens and How BackOps Authorizes API Calls
How the BackOps API layers a sign-in or API key with organization, event, collaborator and area tokens, which header carries each one, and how to get them.
Calls to the BackOps API are authorized in layers. Your credential says who you are. A scoped token says where you are working, such as one organization or one event, and carries the permissions you hold there. This page is for developers and integrators calling the API directly; people using the app never handle these tokens, because the app requests them in the background.
The layers mirror the permission layers described in how permissions work: a scoped token exists for each place a permission can apply.
Your credential
A signed-in or integration request carries a credential in the standard header:
Authorization: Bearer <credential>
The credential is one of two things:
- A person's sign-in token, issued when they sign in to BackOps. Calls made with it act as that person, with their permissions.
- An organization API key, for integrations. An organization admin creates one under Settings › API Keys, with an optional expiry; a key with no expiry set lasts one year. The key is shown once, when it is created, and can be revoked at any time. In the Organization and Event APIs, an API key acts for its organization as an organization admin, so it needs no organization token there. It cannot create, list or revoke API keys.
On its own, a credential is enough only for calls that are not tied to a place, such as the authorize calls below.
Scoped tokens
A scoped token is requested from an authorize call and sent in its own header on later calls. Each one names a single place, carries the permissions you hold in that place, and expires after one hour.
| Token | Header | Request it with | Needs on the same request |
|---|---|---|---|
| Organization | x-Organization-Token | GET /Organizations/{orgId}/authorize (Organization API) | Credential |
| Department | x-Department-Token | GET /Departments/{departmentId}/authorize (Organization API) | Credential |
| Location | x-Location-Token | GET /Locations/{locationId}/authorize (Organization API) | Credential |
| Event | x-Event-Token | GET /Events/{eventId}/authorize (Event API) | Credential |
| Collaborator | x-Collaborator-Token | GET /Collaborators/{collaboratorId}/authorize (Event API) | Credential and event token |
| Area | x-Area-Token | GET /Areas/{areaId}/authorize (Event API) | Credential and event token |
Each authorize call returns a JSON body whose token field is the scoped token.
flowchart TD
K["Credential: sign-in token or API key"] --> O["Organization token"]
O --> Dp["Department token"]
O --> Lc["Location token"]
K --> E["Event token"]
E --> C["Collaborator token"]
E --> A["Area token"]The Organization API reads organization, department and location tokens. The Event API reads organization, event, collaborator and area tokens, so an organization token issued by the Organization API also works for organization-level calls on the Event API, such as listing the organization's events. The Communications and AI APIs read organization and event tokens.
Which token a call needs
Send the token for the place the call works on, alongside your credential:
- Organization pages and libraries, such as the crew database or the organization's events list, need the organization token.
- Anything inside an event needs the event token.
- A call about one collaborator or one area needs the collaborator or area token as well as the event token. An event admin is the exception: their event token already covers every collaborator and area on the event, so they can skip those tokens.
A collaborator or area token is valid only together with the event token of the event it belongs to. If the two do not match, the call is refused and you need to request the collaborator or area token again under the right event.
The API reference describes the permission each operation needs.
When a token is refused
| Response | Usual cause | What to do |
|---|---|---|
401 | A scoped token is expired, malformed, issued to a different person than the credential, or was withdrawn because the person's permissions changed | Call the matching authorize operation again and use the new token |
401 or 403 | The call needs a scoped token and none was sent (401 for a missing organization or event token, 403 for a missing collaborator or area token) | Request the token the call needs and send it in its header |
403 | The token is valid but does not carry the permission the call needs | Ask an admin for the permission; a new token does not help until it is granted |
Requesting an event token itself can fail for reasons that a new token will not fix: the event does not exist or is being deleted, the event's type requires its intake to be completed before people enter, the person's license is not valid for the event, or they hold no usable permissions on it.
When a person's permissions change, BackOps withdraws the tokens that carried the old set. Event, collaborator and area tokens stop working straight away. An organization token presented to the Event API keeps working until it expires, at most one hour.