# API Keys

API keys let you authenticate with the admin API without going through the OAuth flow. They're useful for CI/CD pipelines, scripts, and any automation that needs to manage your HappyView instance programmatically.

## How API keys work

Each API key is a 35-character token with the format `hv_` followed by 32 random hex characters:

```
hv_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
```

When you create a key, HappyView shows the full token **once**. After that, only the prefix (`hv_a1b2c3d4`) is stored for display — the key itself is SHA-256 hashed before being saved to the database. This means nobody (including you) can retrieve the full key after creation.

Each API key has its own set of **scoped permissions**. When you create a key, you specify which permissions it should have. The key's effective permissions are the **intersection** of the permissions assigned to the key and the permissions of the user who created it — a key can never have more access than its creator. A revoked key immediately stops working.

## Creating a key

1. Go to **Settings > API Keys** in the dashboard sidebar
2. Click **Create API Key**
3. Enter a descriptive name (e.g., "CI Deploy", "Monitoring Script")
4. Select the permissions the key should have
5. Copy the full key from the confirmation dialog — you won't see it again

## Using a key

Pass the key as a Bearer token in the `Authorization` header:

```sh
curl http://localhost:3000/admin/lexicons \
  -H "Authorization: Bearer hv_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
```

This works for all [admin API](../reference/admin-api.md) endpoints that the key has permissions for. Unlike OAuth tokens which carry the user's full permissions, API keys are limited to the specific permissions assigned at creation time.

## Revoking a key

1. Go to **Settings > API Keys**
2. Click **Revoke** next to the key
3. Confirm in the dialog

Revoked keys are soft-deleted: they remain visible in the table (with a strikethrough) for audit purposes but can no longer authenticate. Any service using the key will immediately receive `401 Unauthorized` responses.

## Tracking usage

The **Last Used** column in the API Keys table shows when each key was last used to authenticate a request. Keys that have never been used show "Never". This helps you identify unused keys that can be safely revoked.

## Security considerations

- **Treat API keys like passwords.** Anyone with the key can access your HappyView instance with the key's permissions.
- **Use the principle of least privilege.** Only grant the permissions a key actually needs. A CI deploy key probably only needs `lexicons:create` and `backfill:create`, not full access.
- **Use descriptive names** so you can identify which service uses which key.
- **Revoke keys you no longer need.** If a key is compromised, revoke it immediately.
- **Don't commit keys to version control.** Use environment variables or secret managers instead.

## Next steps

- [Admin API reference](../reference/admin-api.md) — full endpoint documentation
- [Scripting](scripting.md) — automate record processing with Lua scripts
- [Index hooks](index-hooks.md) — push records to external services on write