API keys authenticate requests to api.hookdeploy.dev. Create them in the dashboard, use them in scripts and CI, and rotate them regularly.

Creating an API key

Requires the api_keys.manage permission (super admin and admin).

1. Go to Settings → API Keys in your organization
2. Click Create API key
3. Enter a name (e.g. CI pipeline, Local dev)
4. Click Create

The full key is displayed once:

hd_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Copy it immediately. After you close the dialog, only the prefix (hd_live_a1b2...) is visible. The full key cannot be recovered.

Using an API key

Pass the key in every API request:

curl -s "https://api.hookdeploy.dev/v1/health" \
  -H "Authorization: Bearer hd_live_YOUR_KEY"

All routes require authentication, including /v1/health.

Key storage

API keys are stored as SHA-256 hashes in the database — never plaintext. On creation:

1. HookDeploy generates a random key with prefix hd_live_
2. Shows you the full key once
3. Stores only the hash and a display prefix

If HookDeploy’s database is compromised, keys cannot be reversed from hashes.

Security best practices

Do not commit keys to git. Use environment variables:

export HOOKDEPLOY_API_KEY="hd_live_YOUR_KEY"

curl -s "https://api.hookdeploy.dev/v1/endpoints" \
  -H "Authorization: Bearer $HOOKDEPLOY_API_KEY"

In CI (GitHub Actions example):

- name: Check HookDeploy usage
  env:
    HOOKDEPLOY_API_KEY: ${{ secrets.HOOKDEPLOY_API_KEY }}
  run: |
    curl -s "https://api.hookdeploy.dev/v1/usage" \
      -H "Authorization: Bearer $HOOKDEPLOY_API_KEY"

Use separate keys per environment. Create one key for CI, one for local dev, one for production automation. Revoke individually without affecting others.

Set expiration dates when creating keys for temporary access (e.g. contractor access for 30 days). Expired keys return 401 unauthorized.

Scope keys to one organization. Each key belongs to a single org. All API operations are scoped to that org’s endpoints and requests.

Revoking a key

1. Go to Settings → API Keys
2. Click Revoke next to the key
3. Confirm

Revocation is immediate. Any in-flight requests with the old key fail on the next auth check (cached for up to 30 seconds in KV).

Revoked keys cannot be un-revoked. Create a new key instead.

Key rotation

To rotate without downtime:

1. Create a new API key
2. Update your environment variables / CI secrets with the new key
3. Verify the new key works (GET /v1/health)
4. Revoke the old key

There is no grace period — old and new keys work simultaneously until you revoke the old one.

Rate limits per key

Each API key inherits rate limits from the organization’s plan:

Rate limit headers are included in every response. See API overview for details.

Audit logging

API key creation and revocation are recorded in the audit log. Each entry includes the actor, key name, and timestamp.

Next steps

• API overview — Authentication and rate limits
• Endpoints API — First API call after creating a key
• Roles & permissions — Who can manage keys