Authentication
How to authenticate with the Jobiflow Public API using API keys and scopes
Authentication
Every /public/v1/ endpoint takes an API key in the X-API-Key header:
GET /public/v1/job-listings
X-API-Key: jf_live_...API Keys
Creating an API Key
The company owner creates keys on the Jobiflow dashboard under Settings → API Keys: a label, one or more scopes and, optionally, an expiry date. Only the owner of the company can create and revoke its keys.
The full key starts with jf_live_ and is shown only once, right after it is created. Store it in your secrets manager. Afterwards only its first 16 characters (keyPrefix) are shown, with its scopes, its expiry and when it was last used (lastUsedAt).
The key management endpoints (/settings/api-keys, under API Keys in the reference) are the ones the dashboard uses. They take the owner's dashboard login (a bearer token), not an API key.
Scopes
A key may call only the endpoints its scopes allow. Any other call answers 403 with ACCESS_DENIED.
| Scope | Endpoints |
|---|---|
job-listings:read | List and get job listings |
job-listings:write | Create, update, delete, publish and archive job listings, change their status |
applications:read | List, get and count applications |
applications:write | Change an application's status, submit an external application, import a candidate, remove an imported candidate |
candidates:read | Search candidates, get a candidate profile; adds the applicant's email and phone to application responses |
analytics:read | A listing's analytics, the company overview |
webhooks:manage | List, create, update, delete and test webhook subscriptions |
Sectors, tags and enumerations (/public/v1/sectors, /public/v1/tags, /public/v1/enums) answer any valid key.
Scopes are fixed when the key is created. To change them, create a new key and revoke the old one.
Candidate data
- Search (
GET /public/v1/candidates) lists candidates who list their profile on Jobiflow, without email or phone. - A candidate profile (
GET /public/v1/candidates/{jobseekerId}) answers for candidates your company imported, candidates who applied to your listings, and candidates who list their profile. Email and phone are included only for your imports and your applicants. Any other id answers 404 withJOBSEEKER_NOT_FOUND, exactly like an id that does not exist. - Applications carry the applicant's email and phone only when the key also has
candidates:read.
Revoking a Key
The owner revokes a key on the dashboard. A revoked or expired key answers 401 with INVALID_API_KEY from its next request on.
One header only
Send the key in X-API-Key and no Authorization header. A valid key sent with an invalid Authorization: Bearer header answers 401 with TOKEN_INVALID; with a valid bearer token, the scoped endpoints answer 403.
Security Best Practices
- Never commit API keys to version control. Use environment variables or a secrets manager.
- Set an expiry date on every key and rotate keys regularly.
- Give each integration its own key with only the scopes it needs.
- Check
lastUsedAton the dashboard and revoke any key you no longer recognise.