API keys

API keys let you authenticate with the admin API without going through the OAuth flow. Use them for CI/CD pipelines and any other automation that manages your instance.

Key format and permissions

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, and the key itself is SHA-256 hashed before being saved to the database, so nobody (including you) can retrieve the full key after creation.

Each API key has its own set of scoped permissions, chosen when you create it. A key never has more access than the operator who created it; API key permissions explains how the two combine.

Creating a key

1. Go to Access > 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, because you won’t see it again

Using a key

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

TypeScript

const TOKEN = "hv_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4";

const response = await fetch("http://127.0.0.1:3000/admin/lexicons", {
  headers: { Authorization: `Bearer ${TOKEN}` },
});

interface LexiconSummary {
  id: string;
  revision: number;
  lexicon_type: string;
}

const data: LexiconSummary[] = await response.json();

JavaScript

const TOKEN = "hv_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4";

const response = await fetch("http://127.0.0.1:3000/admin/lexicons", {
  headers: { Authorization: `Bearer ${TOKEN}` },
});

const data = await response.json();

Rust

let client = reqwest::Client::new();
let token = "hv_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4";

let response = client
    .get("http://127.0.0.1:3000/admin/lexicons")
    .bearer_auth(token)
    .send()
    .await?;

let data: serde_json::Value = response.json().await?;

Go

token := "hv_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

req, err := http.NewRequest("GET", "http://127.0.0.1:3000/admin/lexicons", nil)
if err != nil {
  log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer "+token)

resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

cURL

curl

curl http://127.0.0.1:3000/admin/lexicons \  -H "Authorization: Bearer hv_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

This works for all admin API endpoints that the key has permissions for. A dashboard sign-in carries the operator’s full permissions, but an API key is limited to the permissions assigned at creation.

Revoking a key

1. Go to Access > 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”.

Security considerations

• Anyone holding a key can access your instance with that key’s permissions, so store it like a password.
• Grant only the permissions the key needs. A key that deploys a project from CI needs only project:deploy.
• Name each key after the service that uses it.
• Revoke keys you no longer use, and revoke a compromised key at once.
• Keep keys out of version control. Use environment variables or a secret manager.

Next steps

• Admin API reference: full endpoint documentation
• API key permissions: how a key’s permissions combine with its owner’s