Authentication

POST /v1/validation requires an active Ivorleaf API credential owned by an explicitly provisioned, active organization. Keep the credential in a trusted server-side environment.

Supported headers

Use the canonical API-key header:

X-API-Key: ivl_...

The endpoint also accepts Authorization: Bearer with an organization API credential. Use one method per request. A validation request also needs Content-Type: application/json and a valid Idempotency-Key; see Idempotency and retries.

curl "$IVORLEAF_API_BASE_URL/v1/validation/usage/status" \
  --header "X-API-Key: $IVORLEAF_API_KEY" \
  --header "X-Ivorleaf-Client: api"

The credential is attributed to its owning organization. Validation capacity is shared across that organization, while usage remains attributable to the credential that performed the work.

Client identity

X-Ivorleaf-Client identifies the integration client when needed. Direct HTTP requests default to api when the header is omitted. If a credential restricts allowed clients, the selected client must be allowed or the API returns 403.

X-Ivorleaf-Client: api

Do not send an invented client value. Send X-Ivorleaf-Client: api for ordinary direct API calls.

Authorization outcomes

401 means the API credential is missing, malformed, or unknown.
403 means a recognized credential, client, or organization cannot use the operation—for example, the credential is inactive, revoked, expired, disallowed for the selected client, lacks explicit organization ownership, or its organization is inactive or not provisioned for Validation Intelligence.

Firebase credentials and API keys that only receive a legacy synthetic organization identity cannot call the commercial /v1/validation boundary.

Store keys safely

Never put a private API key in browser-side JavaScript, a NEXT_PUBLIC_ variable, a public repository, a mobile application bundle, or frontend build configuration. Use a server, serverless function, or trusted backend and keep the key in its secret manager.

Use separate credentials per integration environment where onboarding supports it. Rotate or revoke credentials through the onboarding/support process; public administrative key-management routes are intentionally unavailable.

Get a key

Request API access. The portal does not pretend to provide self-service key creation while onboarding is manual.

Organization execution policy

The organization owns validation execution policy and usage. API keys authenticate into that organization and inherit its policy; credentials cannot select legacy or qualified evaluation. New production organizations default to qualified_v3, hybrid enabled, and vu_v1. Separate V3 entitlement is not required for normal new organizations. Key issuance, rotation, replacement, and revocation do not independently change that policy.

Customers integrate with Validation Intelligence; the underlying evaluator is not a customer configuration choice.