API Keys

Note

You need a permission group with View API Keys access to see this page, and Manage API Keys access to create, edit, or revoke keys. Ask your workspace owner if you don’t see this option.

What is an API key?

An API key is a credential for a program instead of a person: a script, a nightly sync job, or an AI agent that needs to read or write your quotes, clients, or other records without a human signing in each time. If a person needs access to brix, add them as a user instead. Keys are for machines, not people.

Two kinds of key

Every key is made the same way, on this page. The one choice that changes what it can reach is Acts as: leave it blank and the key works for the whole workspace, or name a user and the key is held to what that person can do.

	Workspace key	User key
Acts as	The whole workspace	The user you picked
Sees	Everything in the workspace the key’s scopes allow	Only what that person’s own permissions allow
Best for	Nightly syncs, integrations, anything that runs unattended	An AI agent or personal script working on one person’s behalf

Both sit in the same list, both go in the Authorization header the same way, and both can be revoked here at any time. The Acts as column tells them apart: a workspace key shows Whole tenant, and a user key shows the account identifier of the person it acts as.

Pick a workspace key when the program is part of your business’s plumbing and shouldn’t stop working if one person leaves. Pick a user key when the program is doing someone’s own work for them, and shouldn’t be able to reach anything that person couldn’t reach by signing in.

Where to find them

Go to Manage → Settings → API Keys.

Creating a key

1. Go to Manage → Settings → API Keys.
2. Click Create API Key.
3. Enter a name that identifies what will use the key, for example “nightly-sync” or “quote-bot”.
4. Select the scopes the key needs. See Scopes below, and grant only what the script or integration actually uses.
5. Choose who the key acts as. Leave it blank for a workspace key. Search for a user to tie the key to them, so it can only reach what they can reach — see Two kinds of key.
6. Choose how long the key should last: 30, 60, 90, 180, or 365 days. You can also select Never expires — see Rotating before expiry for the trade-off before you choose it.
7. Click Create API Key.

Danger

The key is shown once, right after you create it, and brix cannot show it to you again. Copy it somewhere safe before you close the dialog. If you lose it, revoke the key and create a new one. See Rotating before expiry.

Giving a key to an AI agent

An agent needs three things: the key, the address to call, and the scopes it is allowed to use. There is no separate connection flow — create the key on this page, decide what it acts as, and hand it over.

If the agent is doing your own work for you, set Acts as to yourself when you create the key. The agent is then held to your own permissions, and anything you can’t do in brix it can’t do either. If it is running unattended for the business, leave Acts as blank and give it only the scopes it needs.

Caution

A key is a password. Paste it into the agent’s own configuration or secret store, not into a chat message, a shared document, or a file you commit. Anyone holding the key can do everything it allows until you revoke it here.

Give your agent these instructions

Copy the block below with the copy button in its corner, paste it to your agent, and fill in the key. It has everything the agent needs to start.

Use this brix API key on every call as the header
  Authorization: Bearer <paste the key here>

All calls start with https://api.brixco.io/api/v1/ — there is no separate
workspace header, because the key already identifies the workspace.

Before doing anything else, confirm the key works with
  GET https://api.brixco.io/api/v1/whoami
That tells you the workspace, the key's name, the scopes you have, your rate
limit, and when the key expires. Stay inside those scopes — a call outside them
comes back as a 403 with code 1009, and no amount of retrying will change that.

You are limited to 600 calls per minute. Every response carries
X-RateLimit-Remaining; if you do run out you get a 429 with a Retry-After
header, and you should wait that many seconds rather than retrying immediately.

Never print the key, log it, or write it into a file.

Scopes

Each key is limited to specific scopes: the parts of brix it’s allowed to touch. A scope has two parts, a resource and an action, written as resource:read or resource:write. For example, clients:read lets a key look up client records but not change them; quoteRequests:write lets it create or update quote requests.

Two wildcard scopes cover everything at once:

Scope	Grants
*:read	Read access to every resource.
*:write	Write access to every resource.

The full list of resources is shown in the scope picker when you create or edit a key, so pick from there rather than guessing a resource name. A few resources cover more ground than their name suggests: listing a quote request’s options needs the same quoteRequests:read scope as the quote request itself, because brix matches a scope to the first part of a call’s address, not the whole thing.

On a user key, scopes are a ceiling rather than a grant: the key is limited to the scopes you gave it and to what that person’s own permissions already allow. Granting a scope covering something they can’t do themselves doesn’t get the key access to it.

What a key can never do

Two things are off-limits no matter which scopes you grant:

• Managing other keys. A key cannot create, edit, or revoke API keys, including itself. Only a signed-in user with the right permission can do that. This holds for a user key as well, even though it acts as a person — otherwise a leaked key could quietly mint itself a second one.
• Reaching brix’s internal admin tools. Keys are scoped to your workspace’s own data and can’t call the parts of brix reserved for brix staff.

Statuses

Status	Meaning
Active	The key is valid and can be used. A key with an expiry date stays active until that date or until it’s revoked; a key set to Never expires stays active until someone revokes it.
Expired	The key’s expiry date has passed. It can’t be reactivated; create a new one.
Revoked	Someone revoked the key. This can’t be undone; create a new one if the integration still needs access.

Expired and revoked keys stay in the list so you can see what existed. The list opens filtered to Active for that reason — switch the filter above the table to All statuses to see the rest.

Using a key

Add the key to every call’s Authorization header, using the Bearer scheme:

Authorization: Bearer brix_00000000-0000-0000-0000-000000000000_XXXXXXXXXXXX_YYYY...

Unlike signing in as a user, you don’t add a separate workspace header. The key’s second segment is your workspace ID, so brix reads the workspace directly from the key, and a key only ever sees the workspace it was created in.

Start with whoami

The first call any integration should make is a self-check:

curl -H "Authorization: Bearer brix_00000000-0000-0000-0000-000000000000_XXXXXXXXXXXX_YYYY..." \
     https://api.brixco.io/api/v1/whoami

This confirms the key works before you build anything on top of it. It returns the workspace the key belongs to, the key’s name, its scopes, its rate limit, and when it expires, so a script can check its own access instead of guessing.

Rate limits

Every key has a limit of 600 calls per minute by default. Each response carries three headers so a script can track its usage without waiting for a failure:

Header	What it tells you
X-RateLimit-Limit	The key’s limit for the current minute.
X-RateLimit-Remaining	How many calls are left in the current minute.
X-RateLimit-Reset	When the current minute ends, as a Unix timestamp.

If a script goes over the limit, brix returns a 429 response with a Retry-After header giving the number of seconds to wait. A well-behaved integration backs off until that time passes instead of retrying immediately.

Errors

A call made with a key can fail in a few specific ways. Each error includes a numeric code your script can check:

Code	Meaning	What to do
1000	The request was invalid	Check the data you sent against what the call expects.
1001	Unauthorized	Check that the Authorization header is present and correctly formatted.
1003	Not found	The record doesn’t exist, or isn’t in the key’s workspace.
1004	Internal error	Something went wrong in brix. Retry later, and contact support if it persists.
1006	Invalid key	The key doesn’t exist, is malformed, or the secret is wrong. brix doesn’t say which, so a key can’t be used to guess valid key IDs.
1007	Key expired	Rotate to a new key. See Rotating before expiry.
1008	Key revoked	The key was revoked and can’t be reactivated. Create a new one.
1009	Scope denied	The key is missing the scope this call needs, or the call isn’t available to keys at all. See What a key can never do.
1010	Rate limited	Back off using the Retry-After header before retrying. See Rate limits.

Rotating before expiry

Most keys should expire. The longest expiring option is 365 days. Set a reminder ahead of a key’s expiry date and create its replacement in advance, so an integration doesn’t stop working when the old key runs out. Because the whoami call returns the key’s expiry date, a script can check its own key and warn you before it lapses.

Choosing Never expires

Never expires removes that safety net rather than adding one: the key keeps working indefinitely, with nothing to force you back to this page to deal with it. That’s convenient for a key you’ll actively manage, but it also means a forgotten key stays live forever — even after the script or integration that used it is gone, quietly widening what an attacker could reach if it ever leaked. Choose it only for a key you’re confident you’ll remember to revoke yourself, and prefer a normal expiry for everything else.

Editing and revoking a key

1. Go to Manage → Settings → API Keys.
2. Find the key in the list.
3. Click it to change its name or scopes, or click Revoke to disable it.

Caution

Revoking a key takes effect immediately and can’t be undone. Any integration still using that key stops working right away.

Things to check

A script gets an invalid key error even though the key looks right

Create a new key and copy the secret again. The secret is shown once and brix cannot recover it later, so a partially copied or mistyped key will always fail. If the key is older, check whether it has expired or been revoked on the API Keys page.

A call keeps returning a scope error

Open the key on the API Keys page and confirm it has the scope the call needs (see Scopes). If the call touches a nested address, check the scope for the first part of the path, not the last. See the quoteRequests:read example under Scopes.

A script that worked yesterday suddenly fails

Check the key’s status on the API Keys page. It may have expired or been revoked since it was created. Create a new key if needed and update the script with the new value.

Frequently asked questions

Can I see a key’s secret again after I close the create dialog?

No. brix never stores the secret in a form it can show you again. If you lose it, revoke the key and create a new one.

Can more than one script share a key?

Yes, but a shared key can’t tell which script made a given call, and revoking it affects everything using it. Create a separate key for anything you might need to turn off on its own.

What happens to a user key if that person’s permissions change?

The key follows them. It’s always limited to what that person can do at the time of the call, so narrowing their permissions narrows the key immediately, with nothing to update on this page. If they leave, revoke the key here.

Does a key expire sooner if it isn’t used?

No. A key expires only when it reaches its expiry date, whether or not it was used in between. There’s no separate inactivity timeout.

PermissionsControl who can view or manage API keys with the View API Keys and Manage API Keys permissions.

Manage & SettingsOverview of all admin configuration areas.