API keys
Create, limit and revoke API keys, and choose which targets a key may pentest.
An API key acts as the person who created it, in the account it was created in. It can never do more than its creator can do, and it stops working the moment its creator loses access.
Creating a key
Open Settings, then API keys, in the dashboard. Every key has:
- A name, so you can tell your keys apart in the list and in your credit history.
- Permissions. Pick only what the key needs.
- A credit budget per billing cycle. Required, so no key can spend without a ceiling.
- An expiry: 1 day, 7 days, 30 days, 3 months, 1 year, or never.
The full key is shown once, when you create it. Barrion stores only a hash of it, so a lost key cannot be recovered; create a new one and revoke the old.
Keys look like this:
brr_live_4f2a9c1e8b7d6a50_...Keys from barrion.io start with brr_live_. Keys made on Barrion's test environment start with brr_test_, and each only works on the environment it was made on: a test key sent to the live API is refused as belonging to a different environment.
The 16 characters after brr_live_ are the key's prefix. It is shown in the dashboard, so you can match a key you find in a log or a repository to the one in your list.
Sending a key
Put it in the Authorization header on every request:
Authorization: Bearer brr_live_...A key always acts on the account it was created in. You cannot point it at another organization.
Permissions
| Permission | Allows |
|---|---|
credits:read | Reading your balance and credit history |
scans:read | Reading passive scans and their findings |
scans:write | Starting passive scans |
pentests:read | Reading pentests, what they cost, and their findings |
pentests:write | Starting and cancelling pentests |
In an organization, a key's permissions are also capped by its creator's current role. A key created by a Viewer cannot start a pentest, whatever permissions it was given. If the creator's role changes, their keys change with it.
The credit budget
Every key has a budget: the most credits the runs it starts may take in one cycle. The cycle is your subscription's current billing period. Without a subscription, it is the calendar month in UTC, so it resets at midnight UTC on the first of each month.
- A pentest counts at its full reserved amount until it is settled. Then only what it was charged stays counted, and the rest is freed.
- A start that would take the key past its budget is refused with
API_KEY_CAP_EXCEEDED. - The budget applies on top of your balance, and in an organization on top of your own spending allowance. Whichever limit is lowest decides.
The keys list shows each key's usage this cycle: what finished runs were charged, what running ones are holding, and when the cycle resets. You can change a key's budget at any time.
Targets for API pentests
A key cannot pentest a target just because the target is verified. Each target has its own API runs switch, off by default. Under your API keys in Settings, turn it on for each target your pipelines may test.
- A start against a target with API runs off is refused with
TARGET_API_RUNS_DISABLED. - Turning it off stops new API starts. Runs already going carry on.
- It only affects the API. Starting a pentest from the dashboard is unchanged.
- Only someone who can manage targets in the account can change it.
An API pentest actively attacks its target. Turn on API runs only for environments your pipeline is meant to test, and think twice before turning it on for production.
Revoking a key
Revoke a key from the keys list. It stops working on the next request, and it cannot be turned back on. Revoking does not stop runs the key already started.
A key also stops working when it expires, or when its creator leaves the organization or has their account suspended.