Authentication

HarborGuard accepts three credential types. Every API route resolves the caller through exactly one of them and rejects the request with 401 UNAUTHORIZED if none match.

Credential	Header	Scope	Best for
Session cookie	Signed session JWT (set automatically)	The signed-in user	The web dashboard
API key	`X-API-Key` or `Authorization: Bearer hg_ak_...`	Organization-wide service identity	CI/CD, sensors, automation
Personal Access Token (PAT)	`Authorization: Bearer hg_pat_...`	A specific user	Personal scripts, ad-hoc tooling

Session authentication

Browser requests authenticate with the session cookie issued at sign-in. The cookie carries a signed JWT containing the user's ID, organization, and role. There is no raw cookie value to copy — sessions only work in the browser. All API responses to a session-authenticated request inherit the user's role.

API keys

API keys identify an organization-level service principal. They are minted from Settings → API Keys in the dashboard and shown to you exactly once.

Format: hg_ak_ followed by 48 hex characters.
Default role: ci (intended for pipelines). The role can be raised when the key is created.
Stored hashed (SHA-256); the plaintext is never written to the database.
Optional expiration date — expired keys return 401.
Optional registry scope — sensor keys are bound to a single registry.

Send the key in either header:

curl https://harborguard.co/api/scans \
  -H "X-API-Key: hg_ak_abcd1234..."

Each successful API-key request bumps the key's lastUsed timestamp asynchronously, so you can audit dormant keys from the UI.

Personal Access Tokens

PATs identify a specific user. They are useful when a script needs to act as a real person — for example, performing triage updates that should appear in the audit log under that user's name.

Format: hg_pat_ followed by 48 hex characters.
Created from Profile → Personal Access Tokens.
Inherit the user's role at the time of the request (role changes propagate immediately).
Sent only via Authorization: Bearer hg_pat_....

curl https://harborguard.co/api/vulnerabilities/CVE-2024-1234/triage \
  -X PUT \
  -H "Authorization: Bearer hg_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "ACKNOWLEDGED", "note": "Tracked in JIRA-481"}'

Role hierarchy

Every credential resolves to a role. Endpoints declare a minimum role; calls below the threshold receive 403 FORBIDDEN.

Role	Level	Typical permissions
`owner`	100	Billing, organization deletion, all admin powers
`admin`	80	Manage members, registries, policies
`developer`	60	Create scans, update triage, generate reports
`ci`	50	Default for API keys; create scans and upload sensor results
`auditor`	40	Read-only access including compliance evidence
`viewer`	20	Read-only dashboard access

Storing credentials

Never commit API keys or PATs. Provide them as environment variables or secrets in your CI provider, and rotate them on a schedule. HarborGuard hashes credentials at rest and cannot recover the plaintext if it is lost.

Errors

Status	Code	Cause
401	`UNAUTHORIZED`	No credential, expired key, or unknown principal
403	`FORBIDDEN`	Credential is valid but the role is below the endpoint's minimum

See Errors for the full list.