API keys
How an owner or an admin makes a key, what scopes it can carry, how long it lasts, and what to do if one leaks.
3 minute read
An API key lets a program act for your organisation, and only that organisation. It can do only what its scopes allow, and never more than the person who made it can do in the console today: if their role changes, the key narrows with it.
Making a key
- An owner or an admin opens API keys in the company menu.
- Name the key after what uses it, such as "ATS sync".
- Tick its scopes (below) and choose when it expires: 30, 90, 180 or 365 days. Every key expires.
- certo e-mails you a six-digit code. Type it in: a session left open on a shared computer cannot make a key.
- The key is shown once. Copy it into your system's secret store. certo keeps only a fingerprint of it and shows you its last four characters afterwards.
Every owner and admin of your organisation is told by e-mail when a key is made, revoked or suspended, and when one reaches certo in a web address.
Scopes
| Scope | Lets the key |
|---|---|
organisation:read | read your organisation and its members (never their e-mail addresses) |
credits:read | read your verification balance and history |
hiring:read | read positions, invitations, asks and the candidates list with their checklists |
hiring:write | create, change, close and reopen positions |
hiring:invite | invite candidates, withdraw invitations, read a pasted list of people |
hiring:ask | ask to read a passport, withdraw an ask |
candidates:read | read a passport a candidate approved, and the over-18 answer (each read is logged) |
candidates:export | export candidates as PDF or Excel (logged) |
issuance:read | read the records you issued and who claimed them |
issuance:write | issue records in a batch |
webhooks:manage | set up, test and remove your webhook |
Give a key the fewest scopes its job needs. A key that only follows checklists needs hiring:read and nothing else.
How a key acts
Each key appears with your company's members as API key: ATS sync, with the role API key. It is never an owner, an admin or a member as the console knows one: it does only what its scopes allow. Every passport it reads is logged as your organisation's read, the same way a person's read is, and the candidate sees that your organisation read their passport through its API.
Keeping a key safe
- Send it only in the
Authorizationheader. A key put in a web address or a request body is refused, and your owners and admins are told: it is in somebody's logs now. - Never use a key in a web page or an app on a phone. Requests from a browser are refused.
- Optionally limit a key to your own network addresses: requests from anywhere else are refused.
When a key stops working
| What happened | What the API answers |
|---|---|
| It expired | api.key_expired |
| An owner or an admin revoked it | api.key_revoked |
| The person who made it left the company, or their role now allows none of its scopes | api.key_suspended, until another owner or admin adopts it on the API keys page (or revokes it) |
| Their role still allows some of its scopes | it keeps working with those only: a scope the role lost answers api.scope_missing |
If a key leaks
Revoke it on the API keys page, or send one request with the key itself:
curl -X POST https://api.certo.bio/v1/keys/self-revoke \
-H "Authorization: Bearer $LEAKED_KEY"
Anyone holding a leaked key can switch it off this way. Then make a new one.