Documentation

Authentication

Authenticate API requests with an API key in the X-RegEngine-API-Key header.

API Keys

RegEngine uses API keys to authenticate requests. RegEngine issues keys, your workspace ID and the ingest signing secret on request. Request access. There is no self-serve key creation.

Security Warning: Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Key Format

rge_live_Every API key starts with this prefix and is scoped to your tenant. There is no separate test-key environment.

Key Lifecycle

Create: RegEngine issues live keys on request. Each key belongs to one workspace and carries the scopes listed below.
Revoke: Ask RegEngine to revoke a key whenever you need to, for example if it leaks. A revoked key is rejected on subsequent requests.

Scopes

Keys carry scopes in a resource.action vocabulary. The . and : separators are equivalent: records.read and records:read name the same scope. A key only needs the scopes for the endpoints you call:

records.read: GET /records and the record detail, history, ingestion-run and trace endpoints under it
webhooks.ingest: POST /webhooks/ingest
webhooks.read: GET /webhooks/recent and GET /webhooks/chain/verify
fda.read: GET /fda/trace/{tlc} and GET /fda/export/history
fda.export: GET /fda/export, /fda/export/all, /fda/export/v2 and /fda/export/recall
fda.verify: POST /fda/export/verify and the Merkle root and proof endpoints

Scopes do not make a key read-only

Scopes limit which of the endpoints above a key can call. They are not a read-only guarantee: some other operations on the RegEngine backend, for example compliance snapshots, SLA request updates, onboarding steps and the EPCIS intake endpoint (in Preview), accept any valid tenant key without checking a named scope. Treat every key as read-write for its workspace. Keep it on your server, never in client-side code, and ask RegEngine to revoke it if it leaks.

API Key Header

Authenticate your HTTP requests by including your API Key in the X-RegEngine-API-Key header.

HTTP Header

X-RegEngine-API-Key: rge_live_...

Example Request

bash

curl -s "https://regengine.co/api/v1/records?limit=1" \
  -H "X-RegEngine-API-Key: $REGENGINE_API_KEY"

Send the key in X-RegEngine-API-Key. An Authorization header is not accepted. RegEngine takes the workspace from the key, so do not send X-Tenant-ID: a value that differs from the key's workspace is refused with a 403, and it never authenticates a request. The FDA endpoints take your workspace ID as a tenant_id query parameter, and it must match the key.

Ingest requests also carry X-Webhook-Signature, an HMAC-SHA256 of the request body made with the signing secret RegEngine issues. See the Quickstart.

Human administration

Browser administration is separate from the public API.

Staff administration uses an opaque Secure, HttpOnly, SameSite=Lax session cookie and requires a WebAuthn or SSO-authenticated sysadmin for high-assurance actions. Browser sessions and internal workload routes are intentionally absent from public OpenAPI.

Authentication Errors

401Unauthorized

The API key is missing or invalid. Send it in the X-RegEngine-API-Key header. On ingest, a missing or wrong X-Webhook-Signature also returns 401.

403Forbidden

The key lacks the scope this endpoint requires, or an X-Tenant-ID or tenant_id value names a different workspace than the key.