Replace a member's company grants
Scopemembers:writeSets the complete list of companies (NIFs) a MEMBER reaches, each with its
access_level, in one call. The response counts what changed.
- Full replacement: the body is the member's whole set of grants after the call. A
company the member had a grant over and that the body leaves out loses its grant; send
[]to revoke every grant. - All or nothing: either every grant in the body is applied or none is. When a request is rejected, the member's grants stay exactly as they were.
- One grant per company: each
company_idappears at most once ingrants. - Eligible members: grants apply only to
MEMBER.OWNERandADMINreach every company implicitly and cannot receive grants. - Repeatable: sending the same body again changes nothing and reports every grant as
unchanged. - Single company: to change one grant without restating the rest, use
PUT /v1/accounts/{account_id}/members/{member_id}/grants/{company_id}.
Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key
short of the scope an operation needs is answered 403. The scope an operation requires
is shown next to its title, and the full catalogue lives in the Scopes reference.
Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.
In: header
Path Parameters
Your own account, or an account you provisioned. It — not the credential — decides which account the operation acts on; a 403 is returned when you do not reach it, the same response an account that does not exist gets.
uuidMembership unique UUID.
uuidHeader Parameters
Idempotency key to prevent duplicates in sensitive operations.
- Any unique client-generated string (e.g. an order id). A UUID also works but is not required
- Allowed characters: letters, digits,
_and-(max 255 chars) - Retrying with the same key replays the first response when it was a success (2xx) or a
server error (5xx): same status and body, plus the header
Idempotency-Replay: true. After a 5xx other than 503, check whether the operation took effect before retrying with a new key - After a
503, retry first with the same key. If the response carriesIdempotency-Replay: true, the operation may have taken effect: check the resource before using a new key. Without that header, the retry runs the operation once - A 4xx is not stored: the key is released, so the corrected request can reuse it
- Stored responses expire 24 hours after processing
POSToperations that only read data (exports, batch PDF downloads, previews) ignore this header: they run on every call and their response is never stored
The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.
| Status | Code | When |
|---|---|---|
400 | INVALID_IDEMPOTENCY_KEY | The key breaks the format rules above. |
409 | IDEMPOTENCY_KEY_PROCESSING | The first request is still in flight: wait for the Retry-After seconds (2) and retry with the same key a few times. If it keeps answering 409, the first response could not be stored: check the resource instead of retrying. |
409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
^[a-zA-Z0-9_-]+$length <= 255Required. Every grant the member is to hold after the call, at most one per company_id. Send [] to revoke all of them. A missing or null value is rejected with 422 VALIDATION_ERROR, so a misspelled key never revokes anything.
items <= 2000Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08/grants" \ -H "Content-Type: application/json" \ -d '{ "grants": [ { "company_id": "550e8400-e29b-41d4-a716-446655440000", "access_level": "OPERATE" }, { "company_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "access_level": "VIEW" } ] }'{
"success": true,
"data": {
"added": 0,
"updated": 0,
"removed": 0,
"unchanged": 0
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication is required to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "LIVE_CREDENTIAL_REQUIRED",
"message": "This operation changes the real account; it requires a live API key or a dashboard session."
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "MEMBER_NOT_FOUND",
"message": "No member with that id belongs to this account."
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "GRANT_COMPANY_NOT_IN_ACCOUNT",
"message": "One of the specified companies does not belong to this account.",
"details": {
"company_ids": [
"6ba7b810-9dad-11d1-80b4-00c04fd430c8"
]
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please try again in 60 seconds."
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type: text/plain. Supported: application/json"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}List a member's company grants GET
Lists the companies (NIFs) granted to a `MEMBER` and the `access_level` of each. Empty for `OWNER` and `ADMIN`, who reach every company of the account implicitly and hold no grants. **Paginated** with the usual `page`/`limit`, and the usual defaults: without them you get the first 20 grants, not all of them. Read `data.pagination` to walk the rest.
Grant a member access to a company PUT
Grants a `MEMBER` access to one company, or changes the `access_level` of an existing grant. Only the company in the path is touched. - **Scope:** the member's other grants are left exactly as they were. - **`access_level`:** `VIEW` or `OPERATE`. `NONE` is not accepted here — remove access by deleting the grant. - **Eligible members:** grants apply only to `MEMBER`. `OWNER` and `ADMIN` reach every company implicitly and cannot receive grants.