NewInvoice designs and replaceable member grants
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Members

Replace a member's company grants

Scopemembers:write

Sets 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_id appears at most once in grants.
  • Eligible members: grants apply only to MEMBER. OWNER and ADMIN reach 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}.

PUT
/v1/accounts/{account_id}/members/{member_id}/grants
AuthorizationBearer <token>

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

account_idstring

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.

Formatuuid
member_idstring

Membership unique UUID.

Formatuuid

Header Parameters

Idempotency-Key?string

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 carries Idempotency-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
  • POST operations 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.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe 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.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255
grants|null

Required. 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.

Itemsitems <= 2000

Response 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"
  }
}