Authentication

Every request must include your API key in the X-Api-Key header:

X-Api-Key: sk_live_<64 hex characters>

No Bearer tokens, no OAuth, no session cookies. Each key is tied to:

• One organization - the key cannot access data from any other org.
• A set of scopes - the key cannot reach routes outside its scopes. Scopes are assigned by the BuilderBase team based on the access your integration requests.

If a key is missing, invalid, expired, or revoked, you receive 401 INVALID_API_KEY.

How you receive a key

To get a key, the best first step is to Book a call with the BuilderBase team - we’ll scope your integration, agree on the access it needs, and issue a key.

You will then receive your sk_live_... key from the BuilderBase team, delivered via a secure one-time link. The raw key is shown once - store it immediately in your own secret manager. BuilderBase only keeps a hash, so a lost key cannot be recovered, only reissued.

How a request is authorized

When you send a key, the API checks it in this order. Any failed step returns a JSON error (see Error Codes):

1. Valid key - the key must be active, not expired, and not revoked. Otherwise 401 INVALID_API_KEY.
2. Required scope - the key must hold the scope the endpoint requires, else 403 INSUFFICIENT_SCOPE. See Scopes.
3. Your organization - the resource you address must belong to your key’s organization. Anything else returns 403 FORBIDDEN.

Path parameters

All paths are relative to the base URL.

• :id is a UUID.
• :slug is a URL-safe slug.
• Parameters that mention :orgId accept either UUID or slug - the API resolves either form.
• All timestamps are ISO 8601 in UTC (e.g. 2026-06-14T09:00:00.000Z).

Security tips

• Store keys in a secret manager, never in source control or client-side code.
• Use a separate key per integration so one can be revoked without affecting others.
• Request only the scopes you need.