> ## Documentation Index
> Fetch the complete documentation index at: https://api.humdov.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Sending your API key, and what scopes control

Every request to the v1 API must carry your API key in the `X-Api-Key` header:

```bash theme={null}
curl https://api.humdov.app/v1/members \
  -H "X-Api-Key: hd_live_xxxxxxxxxxxxxxxxxxxx"
```

There's no separate organization or domain header — the organization your request operates on is determined entirely by the key itself.

<Warning>
  An API key is a secret. Never put it directly in client-side code (a browser page, a mobile app bundle) — anyone who views the page's source can read it. Call the API from a server you control, or use a Humdov form link / embed instead if you don't have a server (e.g. on Squarespace or Wix).
</Warning>

## Scopes

Each key is granted a specific list of scopes, in the form `{resource}.{operation}` — for example `members.create` or `form_responses.view`. A request fails with `missing_scope` if the key wasn't granted the scope that endpoint requires.

Not every resource supports every operation. Some are read-only (`events.view`, `services.view`, `departments.view`, `forms.view`); others support `view`, `create`, and sometimes `update`. Each endpoint's reference page states exactly which scope it needs.

## Key lifecycle

* **Expiration** — a key can be created with no expiry, or set to expire in 30, 90, or 365 days. An expired key fails every request with `key_expired`.
* **Revocation** — revoking a key from the dashboard is immediate and permanent. A revoked key fails every request with `key_revoked`. Revoking never deletes the key's history — it just stops it from authenticating.

## Common authentication errors

| HTTP status | `error.code` | Meaning |
| - | - | - |
| 401 | `missing_api_key` | No `X-Api-Key` header was sent |
| 401 | `invalid_api_key` | The key doesn't match any key on file |
| 401 | `key_revoked` | The key has been revoked |
| 401 | `key_expired` | The key's expiry date has passed |
| 403 | `missing_scope` | The key doesn't have the scope this endpoint requires |

See [Errors](/errors) for the full response shape.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.