API reference · Authentication

Authentication

Every public endpoint requires a Velora API key passed in the Authorization header. Keys are Stripe-shaped: a namespace prefix, an indexed-lookup segment, and a secret. The secret is hashed at rest.

The Authorization header

Send the API key as a Bearer token on every request:

Authorization: Bearer vlk_live_a3f7b921_c8e4d2f6109a4bc7e2f3859d1a4b0c92

curl -H "Authorization: Bearer $VELORA_API_KEY" \
  https://api.velora.health/api/v2/public/audit/events?limit=10

Use environment variables, a secrets manager, or your platform's equivalent — never inline the key in source control or shell history.

Token format

Keys are 49 characters total and decompose as follows:

Segment	Length	Meaning
vlk_live_	9 chars	Namespace + environment.
<prefix>	8 hex	Indexed lookup key. Visible in your dashboard.
_	1 char	Separator.
<secret>	32 hex	Secret material. Hashed at rest.

One-shot disclosure

The full key is shown exactly once at creation. Capture it then. We cannot show it again — the secret is hashed server-side immediately after the create response is sent. If you lose the secret, rotate (see below).

Scopes

Each key carries a list of opt-in scopes. Endpoints require one or more scopes; calls missing the required scope return 403 Forbidden. Request only the scopes you need — the principle of least privilege applies.

Scope	Grants
audit:read	`GET /audit/events`, `GET /audit/events/{id}`, `GET /audit/webhooks`
audit:export	`POST /audit/export`
webhooks:write	`POST /audit/webhooks`, `DELETE /audit/webhooks/{id}`, `POST /audit/webhooks/{id}/disable`

Rate limits

Each key gets its own bucket. Limits are enforced per-key, not per-tenant, so multiple keys for the same tenant get independent budgets.

1,000 read requests per minute for GET operations.
200 write requests per minute for POST / DELETE operations.

On breach the response is 429 Too Many Requests with a Retry-After header (seconds). Back off and retry; production SDKs should implement exponential backoff with jitter.

HTTP/1.1 429 Too Many Requests
Retry-After: 17
Content-Type: application/json

{ "error": "rate_limit_exceeded", "scope": "read", "retry_after_s": 17 }

Auth error responses

Status	Meaning
401	Header missing, malformed, or signature does not match a known key.
403	Key valid but lacks the required scope, or resource belongs to another tenant.
429	Rate limit exceeded. Inspect `Retry-After`.

No oracle on 401

401 responses use a uniform error body — there is no oracle for distinguishing "wrong format" from "format ok but unknown key" from "revoked" without server logs. This is intentional and prevents enumeration. If you're sure your key is correct, the most common causes are a missing Bearer word, trailing whitespace, or a copy-paste truncation.

Rotation

If a key is exposed (committed by accident, sent in a screenshot, etc.), rotate immediately. The flow is:

Email support@velora.health with the key's 8-hex prefix and the reason. Do not send the full secret.
Operator mints a replacement key with the same scopes and sends it back through a secure channel.
Roll the new key into your secrets manager. Most teams overlap the keys for 24h before revoking the old one to avoid downtime.
Operator revokes the old key. 401 responses begin within seconds of revocation.

A self-serve key-management UI is on the roadmap; until it ships the operator-mint flow above is the supported path.

Provisioning a key

Send the following to support@velora.health:

Your tenant ID (or your tenant's primary domain).
Intended use — programmatic query, SIEM push, or both.
Required scopes from the table above.
Optional: an IP allow-list to bind the key to your egress range.

Keys are minted within one business day. For staging access (a separate base URL and key pool against a non-production tenant), mention it in the same email.

With a key in hand, head to Audit events to make your first call, or Code samples to copy a runnable script.