Authentication¶
Every request carries an API key in the Authorization header:
A key acts as the user who created it, with that user's current roles and access. There is no separate permission model to set up, and a change to the user's role applies to their keys on the next request.
Create a key¶
- In the Breqwatr Cloud Portal (Strata), open your profile and select Manage API keys.
- Select New key.
- Give it a name that says where it's used, such as
ci-pipeline. - Choose how long it lasts, and whether to limit it to one organisation.
- Copy the key from the page that follows.
The key is shown once and can't be retrieved later. If you lose it, revoke it and create a new one.
Keep keys out of source control. They all start with bw_, which makes them easy for a secret scanner to find.
Key lifetime¶
Every key expires, after 30, 90 or 365 days. There is no option for a key that never expires.
The portal emails the key's owner 14 days before it expires and again 1 day before. To replace a key without an interruption, create the new one, move your integration to it, then revoke the old one.
Limit a key to one organisation¶
A key can reach every organisation its owner belongs to, or be limited to one. A limited key treats every other organisation as if it doesn't exist, and stops working if its owner leaves that organisation.
Limit a key whenever an integration only needs one organisation.
Who can create keys¶
Any customer account can create keys. Staff accounts can't hold keys, and nobody can create one while impersonating another user.
Check a key¶
GET /me returns the caller and the key in use. It never returns the key's secret.
When a key stops working¶
| Response | Meaning | What to do |
|---|---|---|
401 token_expired |
The key is past its expiry | Create a new key |
401 invalid_token |
The key is missing, wrong or revoked, or its owner was deactivated or left the organisation it's limited to | Check the header, then create a new key if needed |
403 org_suspended |
The key is fine; the organisation is suspended | Contact support. A new key won't help |
Revoking a key takes effect immediately, and anything using it stops working.