Skip to main content
Send your API key in an X-API-Key header on every request:
A missing or invalid key comes back as 401 with code: "UNAUTHORIZED".

Keys are scoped to one organization

Your key belongs to a single organization, and every query is filtered to it before it runs. You cannot read another organization’s data, and organizationId on any record you create is taken from the key rather than from your request body. Sending your own organizationId has no effect.

Getting a key

API keys are created in the BuildingSwell app, under Organization settings → API keys. There is no public API for managing keys.
The secret is shown once, when you create the key. It cannot be retrieved afterwards, so store it in your secrets manager before you close the dialog. If you lose it, create a new key and revoke the old one.

Permissions

A key carries a role, the same way a user does, and record-level permissions apply to it. A call your key is not permitted to make returns 403 with the permissions it is short of:
Give a key the narrowest role that covers what your integration does. A reporting integration that reads timesheets does not need write access to deliverables.