Data security
How the Hub API protects personal data
How keys and tokens are stored, what each key may do, what is logged, how webhooks are signed, and the extra approval that health and criminal record data need. It ends with what is left for you to do on your side.
- tiers of data
- 2
- access token life
- 60 min
- call log, by default
- 6 months
Two tiers of data
Every area of the API has the same everyday controls. Health and criminal record data has one more gate in front of it.
Tier 1
Personal data
Candidates, bookings, courses, certificates, references and similar records. A key that holds the right scope can use them at once.
Areas
- Hub core (candidates)
- Online Training
- Practical Training
- Virtual BLS Training
- Clinical Interviews
- Clinical Appraisals
- References
- Registration Monitoring
- Training Verification
Controls
- Scoped keys
- IP allowlist and expiry
- Rate limits
- Call log
- Signed webhooks
Tier 2
Health and criminal record data
Occupational Health and DBS and Right To Work. On top of everything in tier 1, your organisation needs a one-off approval from the Hub team in live before a key can call these areas or a webhook can receive their events.
Areas
- Occupational Health
- DBS & Right To Work
Controls
- One-off approval
- Review by the Hub team
- Withdrawn at any time
- No bodies in the call log (Occupational Health health data)
- Access trail
Some tier 1 areas also hold sensitive material, such as clinical assessment reports and what referees write. Give the scopes that open them only to keys that need them. The Hub team chooses which areas need approval, so read the current list from the API instead of writing it into your code.
Keys, tokens and access
What protects the credential, and what a stolen credential could and could not do.
- Keys are stored as a hash
- A key starts with hbk_ and is generated at random. The Hub stores a SHA-256 hash of it and its first eight characters, which are kept so you can tell keys apart. The full key is never stored, so a lost key cannot be shown again: you regenerate it.
- Short-lived tokens
- You exchange a key for an access token that lasts 60 minutes and a refresh token that lasts 7 days. Both are random and only a hash of each is stored. A refresh token works once. Regenerating or deleting a key revokes every token it made.
- Scopes limit what a key can do
- Every endpoint needs one scope, written portal:resource:access, for example occupational-health:requests:read. It is checked on every call, so removing a scope applies at once to tokens already issued. A key can never read another organisation's records.
- IP allowlist
- Give a key up to 20 addresses or ranges (IPv4 or IPv6, with CIDR). An empty list means any address. It is checked on every call, so a change applies at once, and a call from another address is refused with 403 ip_not_allowed.
- Expiry and switching off
- A key can have an expiry date and can be switched off. An expired or switched-off key is refused with 403 key_inactive and its tokens are revoked.
- Rate limits
- A key allows 1,000 calls an hour by default, shared by all its tokens, and answers 429 rate_limited with Retry-After beyond that. Exchanging a key or refreshing a token is limited to 10 calls a minute per address. A few endpoints add per-minute limits of their own.
Calls, logs and records
What the Hub records about your calls, and what it deliberately leaves out.
- Always https
- The API is at https://hub.hbcompliance.co.uk/api/v2 and a webhook endpoint must be an https address. The call log keeps the address you called, so keep personal data out of URLs and send it in the request body.
- A log of every call
- Each call is logged with the time, a reference to the key (never the key), the method and path, the status, the duration, the calling IP address and the request_id. For most endpoints the request and response bodies are kept too, after secrets such as keys and tokens are removed, cut to 16 KB. Only JSON and form bodies are kept. The log is kept for six months by default.
- No bodies for Occupational Health health data
- The Occupational Health endpoints that return health data (request detail, answers, alerts, document, Fit to Work and report downloads) are logged without either body. Other areas, DBS and Right To Work included, are logged with bodies as above, so send only the fields an endpoint needs.
- An access trail
- When Occupational Health data is viewed or downloaded through the API, the Hub also records who did it. The entry holds identifiers only (the candidate, the request or the document) and names the API key as the actor.
- Safe retries with idempotency
- Send an Idempotency-Key with a POST that creates something. For 24 hours the same key with the same body returns the first answer instead of doing the work twice, and a different body is refused with 409. The stored answer is encrypted.
- A label for audit
- An integration can send X-HB-Source (zapier/, sdk/ or mcp/ followed by a version) so staff can tell its calls apart from yours. It is a label only: it changes nothing about what a key may do and is not proof of where a call came from.
Webhooks
The Hub calls your address, so you check the sender, not an IP list.
- Signed deliveries
- Each delivery carries X-Hub-Timestamp and X-Hub-Signature, which is sha256= and the HMAC-SHA256 of the timestamp, a full stop and the raw body, made with your endpoint's signing secret (whsec_). The secret is shown once and can be rotated. The Hub does not enforce a timestamp tolerance, so you choose one: five minutes is suggested.
- Identifiers, not people
- Events carry identifiers, statuses and dates. They leave out names, email addresses, questionnaire answers, review notes and document contents, with two documented exceptions: Training Verification events carry the candidate name you entered, and one Clinical Interviews event carries the outcome and score.
- Public https addresses only
- An endpoint must be an https address that resolves to public internet addresses. Private and reserved ranges are refused, and redirects are not followed.
- Retries and switching off
- A failed delivery is tried up to five times, after pauses of 1, 5, 15 and 60 minutes, with the same event_id each time so you can drop duplicates. After 25 failed deliveries in a row the endpoint is switched off and the people with the Developer permission are emailed. Answering 410 Gone switches it off at once.
Approval for health and criminal record data
In live, Occupational Health and DBS and Right To Work are closed to every key until your organisation has been approved. The approval belongs to your organisation, not to one key, and covers the area's API calls and its webhook events.
Step 1
You ask once
A user who may manage developer settings opens Developer, then API access, in the Hub, chooses the areas and answers four questions: what you will build and how the data will be used, why you need access, who receives the data and where it is stored, and whether you have a lawful basis and a data processing agreement in place.
Step 2
The Hub team reviews
A member of the team approves or rejects the request. You are emailed the decision, and a rejection comes with a reason you can read in the Hub.
Step 3
Keys and webhooks start working
Until then a key that holds the area's scopes is refused with 403 and a code that says why, and a webhook endpoint cannot subscribe to the area's events. Events are never queued for an organisation without approval and are not replayed after it.
Step 4
It can be withdrawn
The team can withdraw an approval later, with a reason. Calls are refused again and events stop at once. Your keys and endpoints are not deleted.
- Every step is recorded
- A request, a withdrawal, an approval, a rejection, a withdrawal of an approval and a change to which areas need approval are each written to the Hub's staff-only activity log.
- Existing integrations
- Organisations that already use one of these areas when the rule starts can be approved by the Hub team without a new request, so a running integration is not cut off. That approval is recorded in the same log.
- Check where you stand
- GET /account/api-access works with any valid key and lists every area with its status: not_required, not_requested, pending, approved, rejected or revoked.
The sandbox uses made-up data
A sandbox is a separate copy of the API. Its data is made up, it never reaches the live Hub, it sends no email or SMS and its keys start with hbk_test_, so they cannot be mistaken for live keys. Do not put real personal data into a sandbox. The approval rule does not apply there, and you can test your handling of it with the X-HB-Simulate-Access header.
Learn about sandboxesWhere each control applies
The same Hub controls apply whichever way you connect. Scroll sideways on a small screen.
| Control | REST API | Webhooks | SDK | MCP server | Zapier | Sandbox |
|---|---|---|---|---|---|---|
| Scopes | Checked on every call | Events limited to portals the key can read | Your key, the same scopes | Your key, the same scopes | Your key. Keys that can read health data are refused | Test keys have scopes too |
| IP allowlist | Checked on every call | Does not apply: check the signature | Applies to the key | Applies to the key | Applies to the key, but Zapier's addresses are shared | Accepted, checked only if you switch it on |
| One-off approval (health, criminal record) | In live | In live: subscribing refused, events not sent | In live, as the API | In live, as the API | Not available in the app | Always open, can be simulated |
| Signed deliveries | Not applicable | HMAC-SHA256 with a secret per endpoint | Helper to check a signature | Not applicable | Zapier cannot verify the sender | Same algorithm and headers |
| Call log | Every call, six months by default | Every delivery attempt in the delivery log | Calls labelled sdk/ | Calls labelled mcp/ | Calls labelled zapier/ | Request log in the developer portal |
| Data | Live data | Live data | Live data | Live data | Live data | Made up |
How long things are kept. The call log is kept for six months by default and then removed automatically. Clinical Interviews report PDFs are available only for a retention period, after which the download answers 410 report_expired, and reference answers are removed after the keeping period each client sets. This page states no other retention period because the platform does not set one. Data you copy out of the API is yours to manage.
Your checklist
The Hub protects its side. These are the things that are yours to do.
- 1
Know your basis first
Have a lawful basis and a data processing agreement in place before you ask for access to health or criminal record data.
- 2
Take only what you need
Call only the endpoints and read only the fields you use. Do not copy whole data sets on the chance they are useful.
- 3
One narrow key per integration
Give it only its scopes, no wildcards, an expiry date and an IP allowlist where you have a fixed address. Keep keys for health data apart from your general keys.
- 4
Keep secrets in a secret store
Keys and signing secrets stay out of code, front-end bundles, tickets and screenshots. Regenerate a key you think has leaked.
- 5
Verify every webhook
Check the signature on the raw body, reject old timestamps, receive over https and drop duplicate event_id values.
- 6
Never log health or criminal record data
Log the request_id and identifiers, not names, answers or file contents. Check that proxies and error trackers do not capture response bodies.
- 7
Keep personal data out of URLs
Addresses end up in logs. Send personal data in the request body.
- 8
Store downloads privately
Keep files in private, encrypted storage with limited access, and name them yourself instead of trusting the file name the server suggests.
- 9
Delete what you no longer need
Delete it everywhere, backups included, under your own retention rules.
- 10
Use the sandbox
Build and test there with made-up data, never with real people.
Your agreements
Your organisation's data protection duties, and any data processing agreement you have with Healthier Business, apply to data you receive through the API in the same way as to data you see in the Hub. Your data protection officer can advise.
Healthier Business privacy policyIf something goes wrong
If you think a key or a signing secret has leaked, or data has gone to the wrong place, regenerate the key on the Developer page of the Hub at once (that revokes every token it made) and rotate the webhook secret. Then tell your own data protection contact and report it to us through the support page.
Report through the support pageRelated
- API access approval
Which areas need approval, how to ask and the error codes.
- Keys and tokens
Create, scope, switch off and roll a key.
- Webhooks
Add an endpoint, check a signature and read the delivery log.
- Sandboxes
Test with made-up data before you go live.
- Rate limits, errors and idempotency
Every error code and how to retry safely.
- Safety of the MCP server
Read-only by default, with health data kept out of summaries.
- Zapier and data protection
What the Zapier app never sends and why.