Getting started
Authentication
Every request needs a token, sent in the Authorization header:
Copy 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 .
Tip For an integration, create a dedicated user with a role that has only the scopes the integration needs, and create the token as that user. If you change the role later, create a new token: existing tokens keep the scopes they were created with.
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
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