# Certiv product API authentication Machine-readable authentication guide for AI agents, assistants, and automated clients integrating with the Certiv product API served from app.certiv.ai. For general Certiv context see https://app.certiv.ai/llms.txt. For the product API schema see https://app.certiv.ai/openapi.json. Full product API documentation lives at https://docs.certiv.ai. For the public, unauthenticated lead-capture API (request a demo, join the waitlist) see https://certiv.ai/openapi.json. ## API surfaces Certiv exposes two distinct HTTP surfaces with different authentication: 1. Product API (account required, bearer-token authentication). 2. Public lead-capture API (no authentication). ### 1. Product API - account required Base URL: `https://api.certiv.ai` The Certiv product API (agent discovery, runtime context, continuous authorization, policy, capabilities, and reporting) is private. It requires a Certiv organization account and is not open for anonymous or self-serve agent access. Access is provisioned per organization. The full, always-current endpoint reference is at https://docs.certiv.ai; the machine-readable schema is at https://app.certiv.ai/openapi.json. ### 2. Public lead-capture API - no authentication Base URL: `https://forms.certiv.ai` (described by the OpenAPI 3.1 spec hosted at https://certiv.ai/openapi.json). - `POST /demo-request` - request a product demo. - `POST /waitlist` - join the product waitlist / newsletter. These endpoints are public and require no credentials. ## Authentication method The product API uses bearer-token authentication over HTTPS. Present the token in the standard `Authorization` header on every request: ``` Authorization: Bearer ``` A token is either an organization-scoped API key or a session token issued to a signed-in user. Both are carried the same way, in the `Authorization: Bearer` header. All requests must be made over TLS; tokens must never be sent as query parameters or over plaintext HTTP. ## Pick a method Certiv exposes a single authentication method for the product API: an organization-scoped bearer token presented in the `Authorization: Bearer` header. There is no interactive authorization-code flow, no dynamic client registration, and no separate agent identity-assertion exchange (`identity_assertion` / `id-jag`) - a caller uses one organization API key, or a session token minted from it, for every request. If you are an autonomous agent this is the only method available to you, and the credential must be provisioned by a human on the organization account first (see Claim below). This guide follows the WorkOS auth.md walkthrough shape; see https://workos.com/auth-md. ## Agent authentication discovery Certiv publishes machine-readable authentication discovery metadata so agents can find how to authenticate without scraping this prose. The metadata follows the OAuth discovery specifications (RFC 9728 and RFC 8414). 1. Protected resource metadata (RFC 9728). Fetch https://app.certiv.ai/.well-known/oauth-protected-resource. It declares the protected resource (`https://api.certiv.ai`), that bearer tokens are carried in the `Authorization` header (`bearer_methods_supported: ["header"]`), the available scopes, and the authorization server that issues tokens. 2. Authorization server metadata (RFC 8414). From the protected resource metadata, follow `authorization_servers` to `https://app.certiv.ai` and fetch https://app.certiv.ai/.well-known/oauth-authorization-server. It declares the `token_endpoint` (`https://api.certiv.ai/auth/login`) where a bearer token is issued. 3. Client provisioning (`agent_auth`). Certiv does not support dynamic client registration. There is no registration endpoint and no `register_uri`, so an autonomous agent cannot self-provision credentials. A human with a Certiv organization account provisions an organization API key from the console at https://app.certiv.ai, or requests access at https://certiv.ai/demo/. 4. Token issuance. Present the provisioned credential to the `token_endpoint` with `POST https://api.certiv.ai/auth/login` to obtain a bearer token, then send it as `Authorization: Bearer ` on every product API request as described below. ## Obtaining credentials 1. Sign in to the Certiv product console at https://app.certiv.ai with an account that belongs to a Certiv organization. 2. Generate or retrieve an API key for your organization from the console, or exchange credentials for a token via `POST https://api.certiv.ai/auth/login`. 3. Treat the key as a secret. Rotate it if it is exposed. Refresh an access token via `POST https://api.certiv.ai/auth/refresh`. If your organization does not yet have Certiv access, request it via https://certiv.ai/demo/. Autonomous agents cannot self-provision product credentials; a human with an organization account completes onboarding. ## Claim There is no automated claim step, because there is no dynamic client registration and no `register_uri` to register against. A human with a Certiv organization account claims a credential by signing in at https://app.certiv.ai and generating an organization API key from the console. That key is the caller's identity - hand it to the agent through your secret store. An organization without Certiv access claims it by requesting a demo at https://certiv.ai/demo/. Once the key exists, the agent uses it directly (see Use the credential below); no additional claim exchange is required. ## Scopes and permissions Access is scoped to the caller's organization. A token only grants access to the organization it was issued for, and to the resources and actions permitted for that account. Roles range across Owner, Admin, Manager, Member, and Viewer, and determine which actions a token may take. Tenant isolation is enforced server-side: a token for one organization cannot read or act on another organization's data. ## Use the credential ``` curl https://api.certiv.ai/policies \ -H "Authorization: Bearer $CERTIV_API_KEY" \ -H "Accept: application/json" ``` Send the token in the `Authorization: Bearer` header on every request. Replace the path with the endpoint you need from https://app.certiv.ai/openapi.json or https://docs.certiv.ai. ## Errors A missing, malformed, expired, or revoked token returns HTTP 401 with a JSON error body. Certiv does not yet emit a `WWW-Authenticate: Bearer` challenge header on that 401; instead the auth requirement is published ahead of time in the discovery metadata, so on a 401 read https://app.certiv.ai/.well-known/oauth-protected-resource to learn the protected resource and how to authenticate. A token that is valid but lacks the scope or role for the requested action returns HTTP 403 - re-check Scopes and permissions above; do not retry without a credential that carries the needed role. A 429 signals rate limiting; back off and retry. On 401, re-issue a token via `POST https://api.certiv.ai/auth/login` (or refresh it, below) rather than replaying the rejected one. ## Revocation Treat the API key as a secret and revoke it the moment it is exposed. A human with the organization account revokes or rotates a key from the console at https://app.certiv.ai; the old key stops authenticating immediately and any bearer token minted from it fails with 401. Session tokens are short-lived and expire on their own; refresh an access token via `POST https://api.certiv.ai/auth/refresh` and stop using a token once its underlying key has been rotated. ## SDK and CLI A Python SDK and CLI are published on PyPI as `certiv`: ``` pip install certiv ``` The SDK reads the API key from your environment and sets the `Authorization: Bearer` header for you. See https://docs.certiv.ai for usage. ## Related discovery endpoints - https://app.certiv.ai/.well-known/oauth-protected-resource - RFC 9728 protected resource metadata. - https://app.certiv.ai/.well-known/oauth-authorization-server - RFC 8414 authorization server metadata. - https://app.certiv.ai/openapi.json - OpenAPI 3.1 spec for the product API. - https://app.certiv.ai/.well-known/openapi.json - same spec at the well-known path. - https://app.certiv.ai/.well-known/ai-plugin.json - agent plugin manifest. - https://app.certiv.ai/.well-known/api-catalog - RFC 9727 API catalog (linkset). - https://app.certiv.ai/agents.json - agent capability manifest. - https://app.certiv.ai/llms.txt - machine-readable platform index. - https://docs.certiv.ai - full product API and authentication documentation.