API keys

API keys are organization-level service credentials. They authenticate API requests as a non-human principal with a configurable role. Use them for CI pipelines, scheduled jobs, and integrations.

For per-user credentials that inherit a member's permissions, see Personal access tokens.

Creating an API key

Settings -> API keys -> Create API key.
Provide:
- Name — human-readable label, e.g. gha-prod-pipeline.
- Role — usually ci. May also be viewer, developer, auditor, or admin. Cannot exceed the role of the creating user.
Copy the secret. It is shown once and never displayed again.

The key format is:

hg_ak_<48 hex chars>

The first 10 characters (hg_ak_xxx) are stored as a non-secret prefix and shown in the UI to help you identify the key in logs.

Authenticating requests

API keys are accepted on either of two headers — they are equivalent.

# Preferred for SDKs and most CI tools
curl -H "X-API-Key: hg_ak_..." https://harborguard.co/api/scans

The server hashes the presented key (SHA-256) and compares against the stored hash. The raw secret is never persisted.

API keys are organization-level. They are not scoped to a specific registry, image, or team. Choose the lowest role that does the job — most pipelines need only ci.

Last used and expiry

Every successful authentication updates lastUsed on the key (best-effort, fire-and-forget). The list view shows last-used timestamps; an unused key is the cheapest one to revoke.

Keys may carry an optional expiresAt. Once expired, requests return 401 UNAUTHORIZED with no further hint. Set expiry on every machine credential — even a 1-year horizon is dramatically better than indefinite.

Rotation

To rotate:

Create a new key with the same role and name suffix -v2.
Roll your CI to the new key (via your secret manager).
Verify successful runs.
Delete the old key.

There is no in-place rotation. Two valid keys at once is intentional — it gives you a cutover window without downtime.

Revocation

Click Revoke in the API keys list, or:

curl -X DELETE -H "X-API-Key: $ADMIN_KEY" \
  https://harborguard.co/api/api-keys/<keyId>

Revocation is immediate. In-flight requests using the key complete; subsequent requests fail. Revocation is recorded as apikey.revoked in the audit log.

Rate limits

API key creation is rate-limited to 10 keys per minute per organization to prevent runaway scripts. Per-key request rate limits depend on the route — see the API reference for each endpoint's quota.