Skip to content
  • There are no suggestions because the search field is empty.

API permissions explained

When you connect another system to Calira, you decide what it can see and change. This article explains how API permissions (scopes) work, what each one allows, and the limits that apply to every integration.

How permissions work

  • Each integration gets only the scopes you turn on when you create its application.
  • Reading and writing are separate. An integration set up for reporting can't create bookings unless you give it a write scope.
  • Every request runs as a real Calira user: the person who authorised the integration. It can do what that user can do in Calira, and nothing more. If that user can't book an instrument in Calira, the integration can't book it either.
  • An integration only works in the labs it was authorised for.

What each scope allows

Scope

What it allows

Endpoints

read_accounts

See labs, departments, organisations and groups

GET /accounts

GET /accounts/{id}

GET /groups

GET /groups/{id}

read_bookings

Read bookings, notes, searches and custom form responses

GET /bookings

GET /bookings/{id}

POST /bookings/search

GET /booking/notes/{booking_id}

GET /custom_form_responses/{id}

GET /equipment/{id}/bookings

read_equipment

Read equipment and training records

GET /equipment

GET /equipment/{id}

GET /equipment/{id}/user_trainings

GET /equipment/{id}/bookings

read_projects

Read projects

GET /accounts/{account_id}/projects

GET /accounts/{account_id}/projects/{id}

read_user

Read the signed-in user's own profile

GET /user

read_users

Read the users in a lab or on a piece of equipment

GET /users/{account_id} GET /equipment/{id}/users

write_bookings

Create and change bookings, notes and invitations

POST /bookings

PATCH /bookings/{id}

POST & PATCH /booking/notes/

POST /bookings/{id}/invitation

GET /equipment/{id}/booking_add_ons

GET /equipment_available_slots/{equipment_id}

write_equipment

Create and change equipment and equipment training

POST /equipment

PATCH /equipment/{id}

POST & DELETE /equipment_training/

GET /equipment/contact_people

Things that catch people out

  • Checking free slots and add-ons needs write_bookings. These checks exist to help make bookings, so they sit with the booking permission rather than a read scope. Two other read calls need more than you might expect: listing an instrument's contact people needs write_equipment, and listing every booking on an instrument needs both read_equipment and read_bookings.
  • The full lab member list is for admins and instructors only. Other lab members can list who has access to an instrument only when group bookings are turned on for the lab.
  • All requests are rate-limited. A script that sends more than 1000 requests in 5 minutes will receive an error until the 5 minute period has expired.

Changing or removing an integration's access

To remove an integration's access, go to your API applications page (https://app.clustermarket.com/oauth/applications/) and remove it. You can remove any application your own user account set up. For an application someone else set up, or to change what an integration can do, talk to your customer success manager.

For setup steps, see Does Calira have any APIs available?