# 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](https://www.rfc-editor.org/rfc/rfc6750) has it.

## API keys

An **owner or admin** makes keys in the app, under [Settings → API keys](https://app.hirehappy.io/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:

| Scope                | Allows                                                                               |
| -------------------- | ------------------------------------------------------------------------------------ |
| `jobs:read`          | Listing and reading jobs and their pipeline stages                                   |
| `jobs:write`         | Creating jobs, changing them, opening and closing them                               |
| `candidates:read`    | Listing and reading candidates and the team's notes on them                          |
| `candidates:write`   | Creating, changing and deleting candidates, uploading resumes, adding notes          |
| `applications:read`  | Listing and reading applications, their AI scorecards and interviews                 |
| `applications:write` | Putting candidates forward, moving applications between stages, rejecting and hiring |

Write always comes with read. Each endpoint in the [API reference](https://hirehappy.io/docs/api) shows the scope it needs. Two endpoints need none, so any valid key may call them: [Retrieve your organization](https://hirehappy.io/docs/api/organizations#get-organization) and [Retrieve the API key](https://hirehappy.io/docs/api/api-keys#get-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.

> [!TIP]
> 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.
