The Velora Public API

The Velora API gives customers programmatic access to two surfaces: the audit-trail of every action taken against their tenant data, and the analytics endpoints that drive the dashboards in the portal. Everything is REST-over-JSON, authenticated with a customer-scoped API key in the Authorization header.

The reference is split across five sub-pages. Read them in any order — the index below is the canonical order for first-time integrations.

Reference

• Authentication
  API key format, the Bearer header, scopes, per-key rate limits, and the rotation flow when a key is exposed.
• Audit events
  GET /events (paginated list), GET /events/{id} (single event), POST /export (synchronous bulk export, JSON or NDJSON).
• Webhooks
  Register endpoints, verify HMAC-SHA-256 signatures, handle retries and auto-disable. Includes reference Python + Node verifiers.
• Sidecar mode
  The three PHI modes (server / client / sidecar), when to pick each, the velora-vault tokenizer install + CLI, and the equivalence guarantee.
• Code samples
  cURL · Python · Node gallery. The same five flows in three languages: auth probe, list events, export, register webhook, verify delivery.

60-second quickstart

Three steps from zero to a first authenticated response.

1. Get an API key

API keys are minted by Velora operators. Email support@velora.health with your tenant ID, intended use (programmatic query / SIEM push / both), and the scopes you need (audit:read, audit:export, webhooks:write). The full key is shown exactly once at creation — store it in your secrets manager immediately.

2. Set the Bearer header

Authorization: Bearer vlk_live_a3f7b921_c8e4d2f6109a4bc7e2f3859d1a4b0c92

Keys are 49 characters total — a vlk_live_ namespace prefix, 8 hex chars of indexed-lookup material, and 32 hex chars of secret. The secret is hashed at rest; if you lose the full key you must rotate. See Authentication for the full token format and scope reference.

3. Make your first call

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

You should get back a JSON object with an events array (newest first) and a page block with a cursor for the next page. If you get a 401, check the header format; if you get a 403, the key is missing the audit:read scope.

Environments

There is currently one base URL.

https://api.velora.health

A separate staging environment is available for design partners on request — email support with the IPs / subnets you want allow-listed and we'll provision a staging key.

Conventions

• Versioning. All public routes are under /api/v2/public/. Backwards-incompatible changes bump the major. Tolerate unknown fields in responses; we may add fields without bumping the version.
• Timestamps. ISO-8601 with explicit UTC offset (+00:00). Pass times in the same format — the server normalizes to UTC.
• Pagination. Keyset cursors. Pass the next_cursor from the previous response verbatim; the cursor format is implementation detail and may change.
• Errors. Standard HTTP status codes; 401 for auth, 403 for scope / tenant mismatch, 404 for not-found (also returned for cross-tenant resources to avoid an oracle), 422 for validation, 429 for rate limits, 5xx for Velora-side errors.
• Idempotency. All GET requests are idempotent. Webhook deliveries carry a unique event id — your endpoint should be idempotent on (id, type) to tolerate retries.

PHI handling

Velora supports three PHI-handling modes — server-mode, client-mode, and sidecar-mode — chosen at onboarding. The API key documented here governs audit-trail access; the PHI mode governs how claim and member data crosses the wire. The two are orthogonal: any API key works with any PHI mode.

For the full security model, install steps, and tokenizer CLI reference, see Sidecar mode and the HIPAA technical reference.

Support

Questions, bug reports, integration help: email support@velora.health with your tenant ID and the exact endpoint + status code you hit. Production incidents page a human on-call.