Team members
The people with a login to your Bookline portal and their access, and how to change or remove that access.
The team members endpoints return the people with a login to your account’s portal and their access to it, and let you change or remove that access. Reading needs users:read; changing needs users:write.
| Endpoint | Route | Scope |
|---|---|---|
| List team members | GET /v1/users |
users:read |
| One team member | GET /v1/users/{user_id} |
users:read |
| Replace a team member’s access | PATCH /v1/users/{user_id} |
users:write |
| Remove a team member | DELETE /v1/users/{user_id} |
users:write |
The team belongs to the whole customer: a key limited to some venues gets 403 insufficient_scope. In the examples, $BASE is https://api.bookline.ai/v1 and $BOOKLINE_API_KEY is your key, as in the quick start.
List team members
Section titled “List team members”GET /v1/users returns your team, paged. Takes limit (1 to 100, default 50), cursor and customer_id.
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/users"{ "data": [ { "id": "…", "name": "Ana García", "email": "ana@example.com", "access": [ { "level": "ADMIN", "resource": "ALL", "venue_ids": [] } ] } ], "meta": { "limit": 50, "next_cursor": null }}| Field | What it is |
|---|---|
id |
The team member’s identifier |
name |
Their name |
email |
The address they log in with |
access[] |
Their access to this customer only, one entry per grant |
access[].level |
What they may do: ADMIN, VIEW, CREATE, UPDATE or DELETE |
access[].resource |
What it covers: ALL of the customer, some VENUES, or only BOTS, ACCOUNTS or ACTIVITY (metrics, calls and chats) |
access[].venue_ids |
The venues it covers when resource is VENUES; empty otherwise |
Bookline’s own team does not appear. A partner of yours (an agency or integrator) with access to your account does.
One team member
Section titled “One team member”GET /v1/users/{user_id} returns the same fields, with an ETag header: the version to send as If-Match when you change their access. Someone without access to your account is 404 not_found.
Change a team member’s access
Section titled “Change a team member’s access”PATCH /v1/users/{user_id} replaces the person’s ALL, VENUES and ACTIVITY grants on your account with the list you send. Send their ETag as If-Match (see Writing data).
| Field | Rules |
|---|---|
access |
1 to 20 grants |
access[].level |
ADMIN, VIEW, CREATE, UPDATE or DELETE |
access[].resource |
ALL, VENUES or ACTIVITY |
access[].venue_ids |
Live venues of your account: required when resource is VENUES (up to 200), not allowed otherwise |
curl -s -X PATCH "$BASE/users/<user_id>" \ -H "apikey: $BOOKLINE_API_KEY" \ -H "Content-Type: application/json" \ -H 'If-Match: "<etag>"' \ -d '{"access": [{"level": "VIEW", "resource": "VENUES", "venue_ids": ["<venue_id>"]}]}'BOTSandACCOUNTSgrants are set in the portal only: leave them out and they are kept.- Their access to other Bookline accounts is never read nor changed.
- Only existing team members: inviting someone new is done in the portal (an unknown id is 404
not_found). - The answer is the team member as stored, with their new
ETag. It is personal data: it counts in the 30-per-minute limit and is recorded like a read.
Remove a team member
Section titled “Remove a team member”DELETE /v1/users/{user_id} removes the person’s ALL, VENUES and ACTIVITY grants on your account. Send their ETag as If-Match. The answer is 204.
BOTS and ACCOUNTS grants, set in the portal only, stay; someone left with none is no longer a team member. The person’s login and their access to other accounts stay.
Who can change access
Section titled “Who can change access”Both writes follow these rules, on top of the users:write scope:
| Rule | Answer otherwise |
|---|---|
The key must be an account key, or the key of one of your own users who holds ADMIN on ALL of the account |
403 insufficient_scope |
| A key never changes its own owner’s access | 403 insufficient_scope |
| A partner’s access (an agency or integrator) is set by Bookline | 403 insufficient_scope |
The account keeps at least one of its own users with ADMIN on ALL |
409 conflict |
Every venue_ids entry is a live venue of the account |
422 validation_failed |
The message of each refusal explains it; see why a write can be refused.
Data rules
Section titled “Data rules”- The version covers the whole person. A change to their access on another Bookline account, or to their profile, also changes their
ETag: a write then answers 412. Read them again and resend. - Their API keys follow their new access. A team member’s keys are not revoked: they act with the person’s current access, so narrowed access applies to their keys within about a minute.
Related
Section titled “Related”- Keys and scopes: what each key reads and can change.
- Team: managing your team in the portal.
