> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.beanrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, scopes and what a key is allowed to see.

## Send your key

Pass the key in the `Authorization` header of every request.

```bash theme={null}
Authorization: Bearer brk_live_your_key_here
```

The API accepts bearer keys only. Browser sessions and login tokens do not work here.

## Create and manage keys

Create keys under **Settings** > **API Keys**. When you create a key you choose:

* **Name.** A label so you can tell keys apart, such as the name of the integration.
* **Scopes.** What the key can do. Pick only what the integration needs.
* **Expiry.** 30, 90 or 365 days.

Each key is limited to 60 requests per minute by default. See [Errors](https://api-docs.beanrails.com/errors.md#rate-limits).

BeanRails shows the key once. Store it in your secrets manager. If it leaks, revoke it from the same page; the integration using it stops working immediately.

## Scopes

| Scope | Allows |
| - | - |
| `contacts:read` | List and retrieve contacts and their addresses. |
| `contacts:write` | Create and update contacts and their addresses. |
| `works:read` | List and retrieve works and their proof of delivery records. |
| `works:write` | Create, update, reschedule, cancel and reopen works. |
| `documents:read` | List and retrieve invoices, quotations and invoice payments. |
| `documents:write` | Create invoices and quotations, change their status and record payments. |

A request without the needed scope fails with `403` and the code `insufficient_scope`.

## A key never exceeds its owner

A key acts as the person who created it. Two things follow from that.

> **Roles are checked on every request**
>
> A scope only works while the owner's role still allows it. If you remove contact editing from a member's role, their keys lose `contacts:write` immediately, without being revoked or recreated.

> **Some people only see their own records**
>
> Roles can limit a member to their own contacts, and the works and documents that belong to those contacts. A key owned by such a member sees only that slice. Records outside it return `404`, as if they did not exist, and they never appear in lists.
>
> Creating also respects this. Such a key cannot create a work or document for a contact it cannot see, or link an invoice to a work it cannot see.

> **Assigning documents to other users**
>
> By default a new invoice or quotation is assigned to the key's owner. Setting `user_id` to someone else needs the **assign user** permission on the owner's role.

> [!TIP]
>
> For a company-wide integration, create the key as the workspace owner, or as a member whose role can see everything. A key owned by a restricted member returns only that member's data.

## Keep keys safe

* Use one key per integration so you can revoke one without breaking the others.
* Never put a key in browser code, a mobile app or a public repository.
* Rotate keys before they expire: create the new key, switch the integration over, then revoke the old one.
* If the owner's account is suspended, their keys return `403` with the code `account_suspended`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.