Authentication

Public data needs no credentials. Anything done for an organization needs a credential of that organization: an API key, or a token from an OAuth client. Both are issued in the panel by the organization's owners and admins.

API keys

An API key looks like brl_api_<id>_<secret>. Send it as a bearer token:

GET /v1/org/deals HTTP/1.1
Host: api.birlesa.com
Authorization: Bearer brl_api_01a1...

• Lifetime: 1 to 366 days (90 by default). Plan to rotate: issue the new key, deploy it, revoke the old one.
• Shown once: only a peppered hash is stored.
• Revocation takes effect within a minute everywhere, and at once for actions and for reading organization records.
• People who leave: when someone leaves the organization or stops being an admin, the keys and OAuth clients they created are revoked, and the webhooks they set up are switched off.

Permissions

A key reads public data. What else it may do is fixed when it is issued:

Give each integration only what it uses. A key without a permission gets 403 with code no_org_read (or the equivalent for the action).

OAuth 2.0 client credentials

For machine integrations that should not hold a long-lived key, create an OAuth client in the panel. You get a client_id (a UUID) and a client_secret (brl_ocs_..., shown once). Exchange them for an access token (RFC 6749 §4.4(opens in a new tab)):

POST /oauth/token HTTP/1.1
Host: api.birlesa.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials&scope=org:read

{"access_token": "brl_api_01a1...", "token_type": "Bearer", "expires_in": 3600, "scope": "org:read"}

• The token is an API key that lives one hour. Use it exactly like a key.
• scope narrows the client's permissions; leave it out to get them all. Asking for more than the client has fails with invalid_scope.
• The client may also send client_id and client_secret in the form body instead of HTTP Basic.
• At most 20 tokens of a client are live; a new one beyond that revokes the oldest. Cache a token until shortly before expires_in, and do not request a new one per call.
• Revoking a client revokes its tokens.
• Errors follow RFC 6749: invalid_client (401), invalid_scope, unsupported_grant_type, invalid_request (400), slow_down (429). Responses are never cached (Cache-Control: no-store).

People, not keys

The member panel and the staff console sign people in through Birlesa's identity provider. Their tokens are not API credentials, and API keys do not open the panel. Conversation messages and dispute evidence are only for people in the panel.