Get started
Authentication
Authenticate with organisation-scoped Bearer API keys, choose scopes, and create, store, rotate and revoke keys safely.
Updated
On this page
The Arrota API uses API keys. Each key belongs to one organisation and carries one or more scopes that decide which endpoints it may call.
Send the key
Send the key in the Authorization header on every request:
Authorization: Bearer arr_live_YOUR_API_KEYKeys start with arr_live_. Requests without a valid key receive 401. Arrota gives the same answer for an unknown key and a revoked key.
Create a key
- In your issuer dashboard, open Settings, then API & Webhooks.
- Select Create Key.
- Enter a Label (1 to 60 characters) that says where the key is used, such as "Student information system".
- Choose the Scopes the integration needs.
- Copy the key from the confirmation. Arrota shows the full key once and never again.
Only a Super Admin or Admin can create or revoke keys, and your organisation's plan must include API access.
Scopes
| Scope | Allows | Does not allow | Typical use |
|---|---|---|---|
credentials:read | GET /api/v1/credentials: list the credentials your organisation issued. | Issuing credentials or submitting verification requests. | Reporting, reconciliation, syncing status back to your system. |
credentials:write | POST /api/v1/credentials: issue one credential per request. | Listing credentials (add credentials:read for that). | Issuing from a student information system, LMS or HR system. |
verifications:write | POST /api/v1/verifications and GET /api/v1/verifications/{id}: submit and track verification requests. | Anything about credentials. It also needs an active verifier organisation. | Background-check and screening integrations. |
Give each key only the scopes it needs. A key missing the required scope receives 403 with a message naming the scope.
Store keys securely
- Keep keys on your server, in a secret manager or environment variable. Never ship them in browser or mobile code.
- Use a separate key for each integration so you can revoke one without affecting the others.
- Arrota stores only a hash of each key, which is why a lost key cannot be shown again. Create a new one instead.
Review and revoke keys
The key list in API & Webhooks shows each key's label, prefix, scopes, creation date, Last used and status. Last used updates when the key lists credentials; issuing and verification requests do not update it yet.
Select Revoke to disable a key. Revocation takes effect on the next request, and revoked keys stay in the list for your records.
Rotate a key
Keys do not expire, and there is no one-click rotation. To rotate:
- Create a new key with the same scopes.
- Deploy the new key to your integration.
- Confirm the integration works, then revoke the old key.
Rotate immediately if a key may have been exposed. For security practices across Arrota, see Security.