API Reference

VeriProof exposes two primary REST APIs: the Ingest API for submitting AI governance sessions from your application, and the Customer Portal API for querying, managing, and exporting compliance data from the portal.

APIs at a glance

API	Base URL	Auth	Primary use
Ingest API	`https://api.veriproof.app`	`X-API-Key`	SDK span export, session submission
Customer Portal API	`https://my.veriproof.app/v1`	JWT session cookie	Portal queries, exports, webhooks

Authentication

Ingest API - `X-API-Key` header

All Ingest API requests require an X-API-Key header containing the secondary segment of your compound API key.


POST /v1/ingest/otlp HTTP/1.1
Host: api.veriproof.app
X-API-Key: 3xQr9pLm8N2vT4wK
Content-Type: application/json

The VeriProof SDK handles this automatically - if you configure the SDK with a full compound key, it parses and routes each segment to the correct header.

For direct REST calls (bypassing the SDK), use only the secondary segment in the X-API-Key header.

Customer Portal API - JWT session

The Customer Portal API authenticates using a JWT session token stored in the veriproof_customer_token cookie, set by the portal’s login flow. API calls made from the Customer Portal web application send this cookie automatically.

For programmatic access (CI/CD, integrations), use the portal’s token endpoint:


POST /v1/auth/login HTTP/1.1
Host: my.veriproof.app
Content-Type: application/json
 
{
  "email": "dev@yourcompany.com",
  "password": "..."
}

Returns a JWT token valid for 24 hours.

Compound key format


vp_cust_{customer-slug}.{azure-component}.{secondary-token}

When calling the Ingest API directly, include only the {secondary-token} segment in the X-API-Key header. The full compound key format is consumed by the SDK; individual REST integrations only need the secondary.

See API Authentication for a full explanation of the compound key model.

Environments

Environment	Endpoint	Auth requires
Live ingest	`https://api.veriproof.app`	Standard customer API key
Customer Portal sandbox view	Portal APIs with `X-Veriproof-Sandbox: true` added by the portal client while sandbox mode is active	Customer Portal session auth

The shared sandbox is a read-only Customer Portal mode, not a separate customer API key type. Standard customer API keys authenticate ingest requests; the sandbox header is used by the portal’s sandbox-view override.

The sandbox has no API write path. See Demo & Sandbox.

Common response codes

Code	Meaning
`200 OK`	Request processed successfully
`400 Bad Request`	Invalid request body; check the `errors` array in the response
`401 Unauthorized`	Missing or invalid `X-API-Key`; key not found or revoked
`403 Forbidden`	Authenticated but not permitted to perform the requested action, including mutations while Customer Portal sandbox mode is active
`422 Unprocessable Entity`	Merkle root mismatch - batch hash validation failed
`429 Too Many Requests`	Rate limit exceeded; see `Retry-After` header
`503 Service Unavailable`	Customer account suspended

Rate limits

Rate limits are enforced per API key and scoped to a rolling 60-second window. Current limits are provisioned during prerelease onboarding and surfaced through the standard rate-limit headers returned by the API.

When a rate limit is exceeded, the response includes:


HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712345678

The SDK handles 429 responses automatically using the Retry-After value.

Endpoint Coverage

This overview documents the currently supported base URLs, authentication model, key format, environments, and common response semantics for the public APIs.

Endpoint-specific reference pages are not yet published for this prerelease docs build. Use the SDK reference, product guides, and portal UI flows for concrete integration examples until the dedicated endpoint references are released.

Next steps

API Authentication - compound key model deep-dive
SDK Reference - supported SDKs and configuration guidance
Getting Started - onboarding and first integration steps