Getting started

Authentication

Server-to-server calls authenticate with a per-account API key. Operator actions in the guides authenticate with a workspace session. Nothing else is accepted, and the public record endpoints need neither.

API keys#

Keys are created in the workspace under Settings and are shown once, at creation: Veritura stores only a hash, so a lost key cannot be recovered, only replaced. The workspace lists each key by its display prefix (the first characters, e.g. vk_live_ab12cd) with its last-used time.

Prefix	Environment	Behaviour
`vk_live_`	Production	Writes production records. Passports and unit records issued with it are patient-visible.
`vk_test_`	Sandbox	Writes sandbox records so an integration can be exercised end to end. Never patient-visible.

Authorization: Bearer vk_live_...   # production records
Authorization: Bearer vk_test_...   # sandbox records, never patient-visible

A missing, revoked, expired, or insufficiently scoped key answers 401. Check its permissions and expiry in the workspace before retrying:

{ "error": "A valid API key is required: Authorization: Bearer vk_live_... (or vk_test_...)." }

Live and test environments#

The environment is a property of the key. Responses identify production or sandbox records. Begin document checks and sandbox Passport flows with a vk_test_ key. Public Seal issuance and label retrieval require a live key and production access; those operations are refused in test mode.

Permissions and expiry

New dashboard keys start with Network read access selected. Add only the operations the integration needs. New keys expire after the selected interval; requests at or after expiry are refused. Existing legacy keys retain their previous operations and have no invented expiry. Create a scoped replacement, update your integration, then revoke the old credential.

network:read: directory, source and documented routing lookups.
checks:run: document checks.
decisions:write: ClearGate and eligibility decisions.
passports:write: Passport issuance.
seals:write: Seal batch issuance.
seals:read: Seal label downloads.

The session-authenticated key-creation request accepts a nonempty scopes array and an ISO expiresAt within 366 days. For compatibility, omitted scopes select the existing operation set; omitted expiry defaults to 90 days. Permissions do not bypass workspace entitlements, production gates, or lot-release requirements. These controls apply to vk_ Platform keys, not the separate metered Passport credential.

Request conventions#

All /v1 requests and responses are JSON over HTTPS against base URL https://www.veritura.co.
Field names accept snake_case (canonical, used throughout these docs) and camelCase aliases: lot_id and lotId are the same field.
Every endpoint is rate-limited per key; 429 responses carry a plain-language reason and, where applicable, Retry-After. See errors & rate limits.

Workspace sessions#

The operator-facing endpoints that appear in the guides (paths under /api/…, for example the pharmacist release) authenticate as a signed-in workspace user at www.veritura.co/app, same-origin. They are documented for completeness in the reference overview; a server integration should use the /v1 endpoints.