Authentication

All API requests require an API key passed in the Authorization header.

Key Format

Authorization: Bearer hd_ext_<48-hex-chars>

Example:

Authorization: Bearer hd_ext_a3f7c2d8e1b94f6a7c2e5d9f0a1b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1

Keys follow the format hd_ext_ + 48 lowercase hexadecimal characters (192 bits of entropy).

⚠️

API keys are shown only once at generation time. Store them securely in a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.) — never in source code or logs.

Generating a Key

Open API Keys settings

Go to app.heydonna.chat (opens in a new tab) → Settings → API Keys.

Click Generate Key

Enter a display name (e.g. "My Integration") and click Generate Key.

Copy and store the key

The plaintext key is shown exactly once. Copy it to your secrets manager immediately.

You can have up to 5 active keys per account. Revoke unused keys from the same page.

Code Samples

curl -X POST https://app.heydonna.chat/api/projects \
  -H "Authorization: Bearer hd_ext_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"title": "Smith Depo", "audioUrl": "https://..."}'

Error Responses

Status	Meaning
`401 Unauthorized`	Missing `Authorization` header, invalid key format, or revoked key

{ "error": "Invalid API key" }

See Errors & Rate Limits for the full error reference.

Key Security Best Practices

Environment variables only — never hardcode keys in source code
Rotate regularly — generate a new key and revoke the old one every 90 days
One key per environment — use separate keys for staging and production
Minimum scope — each service/integration gets its own key
Monitor usage — unusual request spikes may indicate key compromise

Overview Endpoints