Docs

Search the docs

Guides, sections and API endpoints

Get started

Authentication

API keys, what each scope allows, expiry and revoking, and keeping keys safe.

Every request carries an API key in the Authorization header, as a bearer token:

HTTP
GET /v1/jobs HTTP/1.1
Host: api.hirehappy.io
Authorization: Bearer hh_sk_...

Requests without one get 401 with type api_key_required; with a wrong, expired or revoked one, 401 with invalid_api_key. Both carry a WWW-Authenticate: Bearer header, as RFC 6750 has it.

API keys

An owner or admin makes keys in the app, under Settings → API keys.

  • A key belongs to the organization, not to whoever made it. It acts for the organization, so it keeps working when its maker leaves. Notes it adds show in the app as added through the API.
  • The key is shown once, when it's made. HireHappy keeps only a hash of it, so a lost key can't be recovered: make a new one.
  • Keys start with hh_sk_, which secret scanners (and people) can recognise. Keep that prefix in mind for your own scanning rules.
  • Name keys after what uses them ("Careers site", "Workday sync"), so you know which to revoke. The app shows each key's last characters and when it was last used.

Scopes

When you make a key, you choose what it may do with each kind of thing. Each choice is a scope:

ScopeAllows
jobs:readListing and reading jobs and their pipeline stages
jobs:writeCreating jobs, changing them, opening and closing them
candidates:readListing and reading candidates and the team's notes on them
candidates:writeCreating, changing and deleting candidates, uploading resumes, adding notes
applications:readListing and reading applications, their AI scorecards and interviews
applications:writePutting candidates forward, moving applications between stages, rejecting and hiring

Write always comes with read. Each endpoint in the API reference shows the scope it needs. Two endpoints need none, so any valid key may call them: Retrieve your organization and Retrieve the API key, which tells you what the key may do:

JSON
{
  "id": "5e1d9a47-2c3b-4f80-8d6e-7a9b0c1d2e3f",
  "name": "Careers site",
  "scopes": ["jobs:read"],
  "expires_at": null
}

A key without the scope an endpoint needs gets 403 with type insufficient_scope. A key's scopes can't be changed once it's made; make a new key with the ones you need, and revoke the old one.

Give each integration its own key with the fewest scopes it needs. A careers site needs only jobs:read; a reporting job, only the read scopes.

Expiry and revoking

Keys expire after 30 days, 90 days or a year, or never; you choose when you make the key. From the moment a key expires or is revoked, requests with it get 401.

To revoke a key, delete it under Settings → API keys. It stops working at once.

Rotating a key

To replace a key without downtime:

  1. Make a new key with the same scopes.
  2. Deploy it to your systems alongside the old one, then switch over.
  3. Check the old key's "last used" time in the app has stopped moving.
  4. Revoke the old key.

Keeping keys safe

  • Server-side only. The API sends no CORS headers, so browsers refuse to call it: a key in a web page or a mobile app is a key anyone can take. Call the API from your server, a background job or a build step.
  • In your secrets, not your code. Read the key from an environment variable or your secrets manager, and keep it out of logs and error reports.
  • If a key leaks, revoke it straight away and make a new one. Revoking is instant.