Skip to main content

​
Send your key

Pass the key in the Authorization header of every request.
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. 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

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