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

# Authentication

> Create and use Public API keys

## API key authentication

Every Public API request must carry your API key in the `X-API-Key` header.

```bash theme={null}
curl https://app.gethuntd.com/api/v1/public/people \
  -H "X-API-Key: hntd_abc12345_yoursecretkey"
```

An `Authorization: Bearer` header is also accepted if that fits your HTTP client better:

```bash theme={null}
curl https://app.gethuntd.com/api/v1/public/people \
  -H "Authorization: Bearer hntd_abc12345_yoursecretkey"
```

## Key format

```
hntd_{8 hex}_{32 hex}
```

The first segment identifies the key; the second is the secret.

## Creating a key

Public API keys are **self-service** — you do not need to contact us.

<Steps>
  <Step title="Open Settings">
    In the [Huntd Dashboard](https://app.gethuntd.com), go to **Settings → API & webhooks**.
  </Step>

  <Step title="Create the key">
    The org owner creates a new key. This does not affect any existing key.
  </Step>

  <Step title="Copy it immediately">
    The key is displayed **once**. Store it somewhere safe before closing the dialog.
  </Step>
</Steps>

<Warning>
  We store only a SHA-256 hash of your key. If you lose it, it **cannot be retrieved** — create a
  new key and revoke the old one.
</Warning>

<Note>
  Keys for the Company Lookup API are provisioned differently — see
  [Authentication](/api-reference/authentication) for that flow.
</Note>

## Multiple keys and rotation

An organization can hold several active keys at once, so rotation needs no downtime:

1. Create the new key.
2. Deploy it to your services.
3. Revoke the old key once nothing is using it.

Revocation takes effect **immediately**. A revoked key returns `401 INVALID_API_KEY` on its next
request.

## Authentication errors

| HTTP Status | Code              | Description                                    |
| ----------- | ----------------- | ---------------------------------------------- |
| 401         | `INVALID_API_KEY` | Key is missing, malformed, unknown, or revoked |

<Warning>
  All four causes return an **identical** response body. This is deliberate — it prevents the
  endpoint from being used to discover which key IDs exist. Branch on `error.code`, never on
  message text.
</Warning>

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key."
  }
}
```

## Security best practices

<AccordionGroup>
  <Accordion title="Store keys in environment variables">
    Never hardcode a key in source. Read it from the environment or a secrets manager at runtime.
  </Accordion>

  <Accordion title="Never commit keys to version control">
    A key pushed to a repository — even a private one — should be treated as compromised and
    revoked immediately.
  </Accordion>

  <Accordion title="Call from server-side code only">
    A key in browser or mobile code is readable by anyone using your app. All Public API calls
    should originate from your backend.
  </Accordion>

  <Accordion title="Use one key per service">
    Separate keys let you revoke a single integration without disrupting the others, and make
    unexpected usage easier to trace.
  </Accordion>
</AccordionGroup>