Access keys and scopes
What a key may do, how long it lasts, and how to replace one without a gap.
What a key is
An access key belongs to one source of one company. It is made on the company's Developer page by someone with the sources.manage permission, after a fresh BankID sign-in. It is shown once, when it is made.
Send it in the Authorization header as a bearer token:
curl https://app.norra.hello-why.com/v1/samples \
--header "Authorization: Bearer $NORRA_KEY"Scopes
A key has one scope, chosen when it is made.
| Scope | Push deliveries | Read samples |
|---|---|---|
read | No | Yes |
write | Yes | No |
read_write | Yes | Yes |
Each operation in the reference names the scopes it accepts. A key without one of them gets 403 with the code insufficient_scope.
The scope is fixed when the key is made. For a different scope, make a new key and revoke the old one. Keys made before scopes existed are write.
Give each system the smallest scope it needs. A billing system that sends numbers gets write. A dashboard that reads them gets read.
Sandbox keys
A sandbox key is stored and parsed like any other key, and what it sends is marked test, so it reaches no report. The receipt and every sample it produced carry "sandbox": true. Use one while you build the integration, then make a live key for production.
Expiry
A key expires a year after it is made, unless you choose a different number of days when you make it. The Developer page shows each key's expiry and when it was last used. A request with an expired key gets 401.
Rotation
Rotate a key before it expires, or as soon as you think it may have leaked.
- On the Developer page, select Rotate on the key.
- Choose how many days the old key keeps working. That is the overlap.
- Select Make the new key and copy it. It is shown once.
- Deploy the new key. Both keys work during the overlap.
- Check that the old key's last use stops moving. After the overlap it stops working.