Scopes
Scopes control which endpoints an API client can access. They follow the pattern resource:permission and are assigned when creating a client in Settings > API Clients.
Customer data scopes
| Scope | Grants | Description |
|---|---|---|
customers:read | GET /customers | List all customers |
profile:read | GET /customer/{id}/profile | Read a customer’s profile |
profile:write | PUT /customer/{id}/profile | Update a customer’s profile |
bookings:read | GET /customer/{id}/bookings, GET /customer/{id}/booking/{bookingId} | Read a customer’s event bookings |
packages:read | GET /customer/{id}/packages | Read a customer’s pass purchases |
videos:read | GET /customer/{id}/videos | Read a customer’s video/media purchases |
subscription-mandates:read | GET /customer/{id}/subscription-mandates | Read a customer’s subscription mandates |
appointments:read | GET /customer/{id}/appointments, GET /appointments/bookings, GET /appointments/bookings/{id}, GET /appointments/services, GET /appointments/services/{id}, GET /appointments/availability/{id} | Read appointments (customer-scoped and company-wide), services, and availability |
notes:read | GET /customer/{id}/notes | Read notes on a customer record |
questionnaire-answers:read | GET /customer/{id}/questionnaire-answers | Read a customer’s questionnaire answers |
Event data scopes
| Scope | Grants | Description |
|---|---|---|
events:read | GET /events, GET /event/{id} | Read the event catalogue (definitions, dates, pricing, properties) |
events-register:read | GET /event/{id}/dates/{dateId}/register | Read the attendance register for a specific event date |
Resource scopes
| Scope | Grants | Description |
|---|---|---|
subscription-plans:read | GET /subscription-plans, GET /subscription-plan/{id} | Read the subscription plan catalogue |
subscription-plans:write | PUT /subscription-plan/{id} | Update subscription plans |
passes:read | GET /passes, GET /pass/{id}, GET /pass/{id}/packages | Read the pass catalogue and active purchases |
passes:write | PUT /pass/{id} | Update passes |
media:read | GET /videos, GET /video/{id} | Read the video library |
media:write | PUT /video/{id} | Update videos |
vouchers:read | GET /vouchers, GET /voucher/{id} | Read the voucher catalogue |
vouchers:write | PUT /voucher/{id} | Update vouchers |
Scope enforcement
- If a client calls an endpoint it doesn’t have a scope for, the API returns 403 Forbidden with a message identifying the missing scope
- The 403 is also recorded in the audit log
- Scopes can be updated at any time via the admin UI without rotating the secret — the next token request will pick up the new scopes
Rate limits
The M2M API has a shared rate limit across all endpoints:
| Limit | Value |
|---|---|
| Rate | 20 requests per minute |
| Burst | 10 concurrent requests |
| Daily quota | 10,000 requests |
Exceeding any limit returns HTTP 429 Too Many Requests. Your integration should implement appropriate backoff and retry logic.
Caching
All read endpoints are cached for up to 5 minutes. This means data returned by the API may trail the database by up to 5 minutes after a change is made via the admin UI or other channels.
- Cache keys are scoped per endpoint, company, resource, and query parameters
- The M2M API uses a separate cache from the admin UI — they do not share or invalidate each other’s entries
- Write operations (e.g.
PUT /customer/{id}/profile) immediately invalidate the relevant cache entry - Identical requests within the TTL window are served from cache without hitting the database
Error responses
All errors return a JSON body with an error field:
| Status | Meaning |
|---|---|
400 | Bad request — missing or invalid parameters |
401 | Unauthorized — invalid or expired token |
403 | Forbidden — token lacks the required scope |
404 | Not found — resource does not exist |
405 | Method not allowed — unsupported HTTP method for this path |
429 | Rate limit exceeded |
500 | Internal server error |
Example 403 response:
{
"error": "Missing required scope: bookings:read"
}
When you receive a 401, request a new token using your client credentials.
Audit logging
Every API call is logged with the following details:
| Field | Description |
|---|---|
| Who | Which API client made the request |
| What | HTTP method, path, resource type, action (READ/UPDATE) |
| When | ISO 8601 timestamp |
| Result | HTTP status code |
This includes denied requests (403), so you can see which clients attempted to access data beyond their scope. Audit entries are retained for 90 days.
You can view audit logs in the admin UI to monitor which clients are accessing what data and when.