Alfa API
Authentication
Every Alfa API request carries an API key as a bearer token. Keys belong to a company, are generated in Alfa, and never act as a signed-in user.
Authorization: Bearer alfa_live_…
Generating a key
An org admin or owner generates keys in Alfa, in Settings › Developers, with Generate key. They choose a name, an environment, the scopes and, optionally, an expiry. The full key is shown once, when it is generated; afterwards Alfa shows only its prefix.
A key is alfa_live_ or alfa_test_ followed by 43 letters and digits.
Environments
| Environment | Key prefix | Host |
|---|---|---|
| Live | alfa_live_ | https://api.welovealfa.com |
| Test | alfa_test_ | https://dev-api.welovealfa.com |
A key works only on its own host. A live key sent to the development API, or a test key sent to production, is refused with 401 unauthorized.
Scopes
Scopes are chosen when a key is generated and cannot be changed later; generate a new key for different scopes. A request without the scope it needs is 403 insufficient_scope. The reference names the scope on each operation.
| Scope | Allows | Default |
|---|---|---|
ats_jobs:write | Create and update ATS jobs. | Yes |
jobs:read | List ATS jobs and the Alfa jobs linked to them. | Yes |
candidates:read | Read candidates and their resumes. | Yes |
webhooks:manage | Set, test and rotate the webhook endpoint; read and redeliver deliveries. | No |
applications:write | Send applicants with applicant intake. Platform keys only. | No |
Company keys and platform keys
A company key belongs to one company and acts only for it. It can leave out the Alfa-Company-Id header; if it names a different company, the request is 403 company_not_connected. A platform key is issued by Alfa to an ATS platform and names a client company on every request. Read about platform keys.
Keeping keys safe
- Store a key as a secret: in an environment variable or a secrets manager.
- Never commit a key to source control, and never put it in front-end code, a mobile app or anything else that runs on a user's device.
- Use test keys for development and testing, and live keys only in production.
- If a key may have leaked, rotate it with no overlap, or revoke it.
Rotating a key
Rotating a key in Settings › Developers issues a new key with the same name, environment and scopes, and moves the old key's webhook endpoints to it. The old key keeps working for the overlap you choose, so you can deploy the new key first:
- Immediately, for a key that may have leaked.
- 1 hour.
- 24 hours, the default.
- 7 days.
When the overlap ends, the old key stops working.
Expiry and revocation
A key can expire 30, 90 or 365 days after it is generated, or never. Revoking a key in Settings › Developers takes effect within a minute and stops its webhook deliveries. A revoked or expired key is refused with 401 unauthorized.
Errors
| Status | Code | When |
|---|---|---|
| 401 | unauthorized | The key is missing, mistyped, revoked or expired, or was sent to the wrong host. |
| 400 | company_id_required | A platform key sent no Alfa-Company-Id header. |
| 403 | insufficient_scope | The key does not have the scope the operation needs. |
| 403 | company_not_connected | The key may not act for the company named in Alfa-Company-Id. |
| 403 | api_not_enabled | The Alfa API is not switched on for the company. Contact Alfa. |
| 429 | rate_limited | Too many requests. Wait for the seconds in Retry-After. |
See every error code and the rate limits, the API reference and the changelog.