All guides
Guide
Authentication
Send your API key on every request. There are two equivalent headers.
Sending your key
curl -s "https://opportunityplatform.co.uk/api/v1/s106" \
-H "Authorization: Bearer $OP_API_KEY"curl -s "https://opportunityplatform.co.uk/api/v1/s106" \
-H "x-api-key: $OP_API_KEY"Both give exactly the same access. Use Authorization: Bearer unless an existing integration already sends x-api-key.
Getting a key
If your organisation (an employer, developer, council, charity or training provider) has a verified account with us, sign in and open API access in your dashboard. You can create, rotate and revoke keys there yourself, up to 20 live keys per organisation. A key is shown once when it is created; we only keep a hash of it. New keys start on the Evaluation allowance (see Rate limits and quotas).
Rotating a key gives you a new one straight away and keeps the old one working for 7 days, so you can switch your integration over without downtime. Revoking stops a key on its next request.
Scopes: what a key can read
| Endpoint | Scope needed | Notes |
|---|---|---|
GET /v1/jobs | jobs:read | Granted at once. |
GET /v1/s106 | s106:read | Granted at once. |
GET /v1/candidates | candidates:read | Personal data. Requested with a purpose and approved by us first. Aggregates only, every call audited. |
POST /v1/compliance-export | compliance:read | Personal data. The one scope you cannot request in your dashboard: our team sets it up on a key, and it reads only the developers that key is allowed to read. |
GET /v1/openapi.json | None | Public, no key. |
/v1/webhooks/endpoints | webhooks:manage | Needs approval: some webhook events carry a pseudonymous candidate reference. Once approved, your organisation can subscribe to those events by any route. See below. |
GET /v1/events | Not a key | Signed-in session only today. See below. |
A scope you have requested but we have not approved yet grants nothing: calls that need it return 403 forbidden_scope until it is approved. Your key does not change when it is approved.
Failures
| Status | code | When |
|---|---|---|
| 401 | unauthorized | No key was sent, or the key is not one we issued, or it has been revoked. The last two are deliberately indistinguishable. |
| 403 | forbidden_scope | The key is valid but not allowed to read this: it lacks the scope (error.required_scope says which), or it is another developer on compliance-export. |
| 429 | rate_limited | The key is over its hourly limit or monthly quota (quota_exceeded). See Rate limits and quotas. |
The full list of codes and the error format are in Errors.
Events and webhook management
Most people manage webhooks without code, in the dashboard under API access, Webhooks. To automate it, /v1/webhooks/endpoints also accepts a key holding webhooks:manage, and acts for the organisation that owns the key. Request the scope on a key from API access with a short purpose; it needs our approval because the candidate.* events it can subscribe to carry a candidate_id, a pseudonymous reference to one person. Until it is approved, calls get 403 forbidden_scope. Key calls are metered like any other.
The approval belongs to your organisation: once any of its keys holds an approved webhooks:manage, it can subscribe to the candidate.* events in the dashboard too, and not before. The same routes also accept the session of a signed-in account of a verified organisation, acting for that organisation exactly as the dashboard does. If a request carries a key, the key alone decides: a wrong key is a 401 even when you are also signed in. /v1/events takes a signed-in session only for now. The Webhooks guide has the details.