Getting started

Authentication

Every request needs a token, sent in the Authorization header:

Authorization: Bearer <your-token>
Accept: application/json

Create tokens in the portal, under Settings → Apps & Integrations → API. The Quickstart walks through it.

What a token can do

Each token carries a set of scopes. When you create a token in the portal, it gets the scopes your account has at that moment, which come from your roles.

You can check a token's scopes with GET /users/me/scopes. Each endpoint in the API reference says which scopes it needs.

Managing tokens

Action How
Create Portal, or POST /oauth/personal-access-tokens with name and scopes. Needs settings.apps-integrations.manage.
List Portal, or GET /oauth/personal-access-tokens
Revoke Portal, or DELETE /oauth/personal-access-tokens/{tokenId}

If a token leaks, revoke it straight away and create a new one.

Errors

Status Body Meaning
401 {"message": "Unauthenticated."} The token is missing, invalid or revoked.
403 {"message": "Invalid scope(s) provided."} The token doesn't have a scope this endpoint needs.
403 {"message": "This action is unauthorized."} The token's user isn't allowed to act on this record.

Scopes

Roles are built from these scopes. Some endpoints need a specific scope and others accept any one of several. If a request returns 403, check the role of the user behind the token.

Core

Scope Allows
read Read all office, desk, bookings and meetings information
write Create and edit bookings and events
admin Perform administrative tasks, such as creating rooms, users and device settings

Desk bookings

Scope Allows
bookings.view View desk availability
bookings.create.own Create desk bookings for themselves
bookings.create.others Create desk bookings for others
bookings.create.guests Create desk bookings for guests
bookings.checkin.others Checkin or checkout desk bookings for others
bookings.delete.others Delete desk bookings for others
bookings.manage.team Create and update and delete bookings for users they manage
bookings.override-same-day-rule (Override) Can make same day bookings
bookings.override-allocations (Override) Can book allocated desks
bookings.override-approvals (Override) Can make bookings without needing approval
bookings.edit.others Can edit the bookings of others
bookings.team-planner Can use the team planner to book desks for multiple users

Parking

Scope Allows
parking.view View parking availability
parking.create.own Create parking bookings for themselves
parking.create.others Create parking bookings for others
parking.create.guests Create parking bookings for guests
parking.checkin.others Checkin or checkout parking bookings for others
parking.delete.others Delete parking bookings for others
parking.manage.team Create and update and delete parking bookings for users they manage
parking.override-same-day-rule (Override) Can make same day parking bookings
parking.override-allocations (Override) Can book allocated parking spaces
parking.override-approvals (Override) Can make parking bookings without needing approval
parking.edit.others Can edit the parking bookings of others
parking.permits.view.own View their own parking permits
parking.permits.manage.own Create, update and delete their own parking permits
parking.permits.manage.others Create, update and delete parking permits for other users in the organisation
parking.misuse.report Report a vehicle occupying their booked parking space and track the outcome
parking.misuse.report.others Report parking misuse on bookings made by others (e.g. reception reporting a taken visitor bay)
parking.misuse.review Review parking misuse reports, log offences and manage offender records
parking.misuse.manage Configure parking misuse reporting settings per office

Meetings and services

Scope Allows
meetings.read View meeting rooms
meetings.manage Book meeting rooms
meetings.override-service-cut-off-times Can override service cut off times
meetings.write.others Edit meetings organised by others
meetings.create.others Organise meetings for others
meetings.override-meeting-approvals (Override) Can make meetings without needing approval
meetings.manage.team Create and update and delete meetings for users they manage
services.provider.read View service provider dashboard
services.provider.edit Edit service orders in dashboard
meetings.override-services (Override) Can book meetings when services are unavailable

Visitors

Scope Allows
visitors.read View all visitors
visitors.manage Create and edit all visitors
visitors.read.own View their visitors
visitors.manage.own Create and edit their visitors
visitors.read.created View visitors they created
visitors.manage.created Create visitors for anyone, edit only visitors they created
visitors.id-document.capture Capture visitor ID documents at the kiosk
visitors.id-document.view View captured visitor ID documents

ArrivalsHQ

The staff, deliveries and emergency scopes are the ones the ArrivalsHQ endpoints use. The rest control ArrivalsHQ setup in the portal, which isn't available through the API.

Scope Allows
arrivals.staff.view View every staff member in the organisation and their attendance
arrivals.staff.manage Update staff attendance and issue staff sign-in codes
arrivals.staff.manage.team Manage attendance, sign-in codes, PINs and badges for your own teams and direct reports only
arrivals.deliveries.view View deliveries
arrivals.deliveries.manage Log, collect and manage deliveries
arrivals.emergency.view View live evacuations and roll calls
arrivals.emergency.manage Start and manage evacuations, fire marshals, assembly points and drills
arrivals.analytics.view View arrivals analytics (insights, fleet health, safety, compliance coverage)
arrivals.logs.view View the arrivals activity log (sign-ins, badge printing, evacuations)
arrivals.compliance.view View the visitor audit trail
arrivals.compliance.manage Edit visitor privacy and data retention settings
arrivals.branding.manage Edit kiosk branding and welcome screen
arrivals.journeys.manage Create and edit visitor journeys and visitor types
arrivals.documents.manage Manage sign-in documents (NDAs and agreements)
arrivals.badges.manage Edit the visitor badge design
arrivals.printers.manage Manage badge printers and the print queue
arrivals.devices.manage Manage arrivals kiosks (pair, configure, lock down)
arrivals.tenants.manage Manage multi-tenant reception groups and tenants
arrivals.hosts.manage Manage the host directory
arrivals.notifications.manage Edit arrivals notification settings
arrivals.suggestions.manage Run and apply AI setup suggestions

Users and roles

Scope Allows
roles.read Read all roles
roles.manage Edit roles
users.read Read all users in the organisation
users.status.view Can view the status section on the profile page
users.status.edit Can edit the status section on the profile page

Reports and attendance

Scope Allows
reports.view View and run reports
reports.manage Create new data exports reports
office.attendance.view View the Who's in page

Settings

Scope Allows
settings.apps-integrations.manage View and edit Apps and Integrations settings and API tokens
settings.billing View plans and billing page
settings.edit View and Edit all settings
settings.working-hours.edit Can edit office working hours
settings.users.manage Can manage user accounts and teams
settings.kiosks.manage Can create and manage kiosks
settings.checkin.read Read organisations check-in settings
settings.services.manage Create and edit available services
settings.custom-emails.manage View and Edit the custom email settings
settings.edit-office-plan Can edit the office plan on the offices page
settings.custom-fields.manage Can manage custom fields
settings.custom-statuses.manage Can manage custom statuses

Events and OpenSpaces

Scope Allows
events.manage Can create, update and delete events
events.read Can read events
openspaces.manage Can manage OpenSpaces settings
openspaces.bookings.manage Can manage OpenSpaces bookings

Assets

Scope Allows
assets.read Read all assets