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?