# Valyd — Identity & Verify API Documentation

> Valyd offers two products in one SDK. **Unique Human API** — API-key-only, no user account:
> create a session for a workflow containing the liveness and/or face-uniqueness checks
> (`verify.sessions.create({ workflowId, redirectUrl })`, NO user token), redirect the person to
> Valyd's verification page, and read the verdict from the decision; nothing is saved to an
> account. **Reusable Verification** — the user connects with Valyd (standard
> OIDC), you read their verified data through `valyd.auth`, run a configured **workflow** on a
> verification session (`verify.sessions.create({ workflowId, valydAccessToken, redirectUrl })`)
> where every check is available (ID/KYC, liveness, face match, age, professional license, face
> uniqueness, location), and passed proofs save to the user's Valyd ID for reuse.
> Verification runs through the SDK on Valyd's verification page — there are no raw verification
> endpoints to call. Everything runs through the Valyd IdP host. This file is the machine-readable
> index of the docs. Every page below is available as clean Markdown at the linked `.md` URL —
> fetch those directly; do not try to scrape the HTML site (it is a client-rendered SPA and
> returns no static content).

## How to integrate (decision flow)

Ask the developer these questions, in order; each answer pins one product + credential + one `.md`
page to fetch and follow. Credentials must be supplied by a human (see "Human-only steps") — never
guess them.

- Q0 (context only): Existing app or starting fresh? Tells you where the connect button and keys go.
- Q1 — Team/workforce you onboard AND control (add members, gate who can log in, assign roles)?
  - YES → **Organizations**. Members join by face-activation, then sign in with Connect with Valyd;
    roles owner/admin/developer/member; the `valyd_org_member_id` claim (a `vmem_…` id) tells you
    who logged in; unlimited verifications on a per-active-member monthly plan (14-day trial;
    current price → https://docs.valyd.vip/docs/organizations/billing.md).
    Credential: `client_id` + `client_secret` (connect) + Members API (`X-Client-Id`/`X-Client-Secret`).
    Fetch: https://docs.valyd.vip/docs/organizations.md
  - NO → continue.
- Q2 — Just need to know a person is LIVE and/or UNIQUE, with only an API key (no login, no
  account, result returned to you, nothing saved)?
  → **Unique Human API**. Create a session with NO user token for a workflow containing the
    liveness (anti-spoof) and/or face-uniqueness checks —
    `verify.sessions.create({ workflowId, redirectUrl })` — redirect the person to `session.url`
    (Valyd's verification page captures a live burst), then read
    `verify.sessions.decision(sessionId)`: antispoof data carries `human_score`; face_uniqueness
    data carries a stable `valyd_uuid` + `registered: "new" | "existing"` (one-person-one-account
    dedup).
    Credential: App key (via the SDK) + `workflow_id`.
    Fetch: https://docs.valyd.vip/verify/unique-human.md
    (Liveness: https://docs.valyd.vip/verify/unique-human/antispoof.md ·
    Uniqueness: https://docs.valyd.vip/verify/unique-human/face-uniqueness.md)
- Q3 — Need reusable verified identity — KYC, ID, face match, age, professional license, location —
  or want to read/write proofs on the user's own Valyd account?
  → **Reusable Verification**. The journey is: **Connect with Valyd** (standard OIDC) → read the
    account's verified data (proofs like `id_verified`, age bands, licenses — free, instant) → run
    a configured **workflow** on a verification session with the user's token —
    `verify.sessions.create({ workflowId, valydAccessToken, redirectUrl })` — → get the decision
    via `verify.sessions.decision()` or a signed webhook. Every check is available (ID/KYC,
    liveness, face match, age, professional license, face uniqueness, location); passed proofs
    save to the user's Valyd ID (reusable across apps); PII stays encrypted with Valyd — you get
    the decision + proofs, never raw PII.
    Credential: `client_id` + `client_secret` (connect) + App key (via the SDK) + `workflow_id` +
    the user's `valyd_access_token`.
    Fetch: https://docs.valyd.vip/verify/intro.md then
    https://docs.valyd.vip/verify/quickstart.md
  NOTE: ID/KYC, face match, age, professional license, and location are NOT direct public APIs —
  they run ONLY as workflow checks inside a Reusable Verification session.
- Q4 — Sign-in only (connect the user, run no check)?
  → **Connect with Valyd** (OAuth2/OIDC — part of Reusable Verification; it can also serve as your
    app's sign-in). Credential: `client_id` + `client_secret`.
    Fetch: https://docs.valyd.vip/docs/authentication.md

Then clarify (as relevant), fetching the named `.md`:
- Which workflow checks? ID/KYC, liveness, face match, age (age *bands* like `is_18_plus`, never
  the DOB), professional license, location/EVV presence, face uniqueness.
  → https://docs.valyd.vip/verify/types.md (Checks reference)
- Reusable identity (KYC-reuse)? Save the passed check as a proof — that's **Reusable
  Verification** (needs the user's `valyd_access_token`). A Unique Human API call saves nothing.
  → https://docs.valyd.vip/docs/user-token.md
- Result delivery? Async signed webhook or `verify.sessions.decision()` (Reusable Verification
  session) vs the synchronous return of a Unique Human API SDK call.
  → https://docs.valyd.vip/verify/webhooks.md and
  https://docs.valyd.vip/verify/statuses.md
- Need RAW identity data (DOB, document number, address)? Requires the consent flow (the user
  approves on their device); otherwise you get proofs / verified-status only.
  → https://docs.valyd.vip/docs/request-data.md
- Connect scopes? profile (legal name, country, verified status), verifications (proofs/badges),
  email, doctor_license. → https://docs.valyd.vip/docs/scopes.md
- Professional license check? Runs as a workflow check in a **Reusable Verification** session (a
  connected user's verification session); the name comes from the account and the verified badge
  saves to their Valyd ID. → https://docs.valyd.vip/verify/intro.md
- Drop-in button or your own OIDC library? "Connect with Valyd" button
  (https://docs.valyd.vip/docs/overview.md) vs any OIDC library via discovery
  (https://docs.valyd.vip/docs/oidc.md).
- Credentials source (IMPORTANT): a human creates the app + keys in the Developer Portal
  (dev.valyd.vip); an agent CANNOT mint `client_id`/`client_secret`/API key/`workflow_id` — pause
  and ask, never guess. → https://docs.valyd.vip/docs/create-project.md
- Billing? Organization = unlimited verifications on a per-active-member monthly plan (billing
  starts the moment a member face-scans); non-org = pay per check. Current price + trial
  → https://docs.valyd.vip/docs/organizations/billing.md

Full narrative version of this tree (with example calls and the two golden rules) is the Agent
Integration Guide, rendered at https://docs.valyd.vip/ai/agent-guide.

## Instructions for AI agents

- Fetch pages with `curl -sL <url>`; each `.md` is self-contained (prerequisites, steps,
  verification, and common errors).
- **Base URLs (one canonical host per product — use these exactly):**
  - Valyd ID / OAuth / OIDC (API host): `https://idp.valyd.vip`
  - Verification API (same host): `https://idp.valyd.vip`
  - Developer Portal (human sign-in, projects, keys): `https://dev.valyd.vip`
  - Documentation (this site, `.md` + OpenAPI): `https://docs.valyd.vip`
- **There is NO password login.** Human sign-in to the Developer Portal is passwordless — an emailed
  magic link OR face ("Connect with Valyd"). Never look for, store, or send a password. Portal
  sign-in, linking a face, and switching accounts are human-only steps an agent cannot perform.
- **Credentials cannot be created via API.** A human must sign up and generate them in the portal
  (see "Human-only steps" at the bottom). Pause and request these values rather than guessing:
  `client_id`, `client_secret` (Valyd ID); App `API key`, `workflow_id`, webhook signing secret
  (Verification APIs).
- Auth is not interchangeable: connect/account endpoints use an OIDC Bearer access token;
  verification runs through the SDK with your App key (server-side). A Reusable Verification
  session also carries the connected user's `valyd_access_token`.
- Token exchange and webhook signature verification MUST run server-side (never expose the client
  secret or webhook secret to a browser).
- **Machine-readable API specs (OpenAPI 3.1):** for endpoint discovery, schemas, and codegen, fetch
  `https://docs.valyd.vip/openapi/valyd-id.json` and `https://docs.valyd.vip/openapi/valyd-verify.json`.
- **Capability matrix (machine-readable):** to pick a path deterministically, fetch
  `https://docs.valyd.vip/agent/capabilities.json` — a JSON array mapping each real goal to its
  `path`, `product`, `auth`, `credential`, `billable`, `pii_mode`, `saves_proof`, and the `.md`
  `doc` to follow (connect, account-read, reusable-verification session, Unique Human API,
  organizations).

## Valyd ID — Getting started

- [Overview](https://docs.valyd.vip/docs/overview.md): When to use OIDC connect, what it reads from an account, and when to run a verification session instead.
- [Create a Project & Get Credentials](https://docs.valyd.vip/docs/create-project.md): Dev-portal setup — sign up, create a project, set redirect/scopes, copy client_id + client_secret. (Human-only.)
- [Quickstarts — Connect with Valyd](https://docs.valyd.vip/docs/quickstarts.md): Stack-by-stack complete flows — Node.js, Next.js, Python, PHP (Laravel), cURL, or any OIDC library — each a full working OIDC flow (state comparison, code exchange, userinfo). (The old /docs/quick-start.md is a compatibility redirect to this page.)
- [OIDC session security](https://docs.valyd.vip/docs/tokens.md): Store and validate state, nonce, PKCE, and redirect URI as one server-side transaction.

## Valyd ID — Authentication & integration

- [Authentication (OAuth2 / OIDC flow)](https://docs.valyd.vip/docs/authentication.md): Connect with Valyd — authorization URL, state/nonce CSRF, callback handling, code→token exchange, refresh rotation.
- [OpenID Connect (OIDC) Integration](https://docs.valyd.vip/docs/oidc.md): Discovery endpoint, manual config, Mendix setup, claim/user mapping, testing, troubleshooting, security.

## Valyd ID — Reference

- [API Reference (endpoints)](https://docs.valyd.vip/docs/endpoints.md): OIDC discovery, authorize, token, JWKS, UserInfo, licenses, and account verification proofs under `/api/auth/oidc`.
- [OAuth2 Scopes](https://docs.valyd.vip/docs/scopes.md): profile, verifications, doctor_license, zkp, mcp — what data each unlocks and how to request them.
- [Errors & troubleshooting](https://docs.valyd.vip/docs/errors.md): Every error code with cause and fix, plus the app-level "state mismatch" CSRF rejection.
- [Changelog](https://docs.valyd.vip/docs/changelog.md): @valyd/sdk release history, including the v1.10.1 secure OIDC transaction helpers.


- [Request user data (consent)](https://docs.valyd.vip/docs/request-data.md): Ask a Valyd user for raw attributes (legal_name, dob, country). The user approves in their Valyd app; values return end-to-end encrypted (X25519 sealed box) via valyd.auth.requestAttributes + getAttributeResult. Needs libsodium-wrappers for self-custody.

## Verification APIs — Guides

- [Reusable Verification](https://docs.valyd.vip/verify/intro.md): The journey — Connect with Valyd, read verified data, run a workflow on a verification session with the user's token, get the decision; every check available, passed proofs save to the account.
- [Run a verification (quickstart)](https://docs.valyd.vip/verify/quickstart.md): Get an App key, connect the user, and run `verify.sessions.create({ workflowId, valydAccessToken, redirectUrl })`.
- [Create a workflow (setup)](https://docs.valyd.vip/verify/setup.md): Developer Portal setup — the App API key (shown once), a `workflow_id`, and the webhook secret. (Human-only UI steps.)
- [Workflows](https://docs.valyd.vip/verify/workflows.md): Configure which checks a verification session runs, in the Developer Portal, and get the `workflow_id`.
- [Unique Human API](https://docs.valyd.vip/verify/unique-human.md): API-key-only, no user account — a workflow session (no user token) on Valyd's verification page running the Liveness and/or Uniqueness checks; verdict returned to you, nothing saved to an account. See [Liveness](https://docs.valyd.vip/verify/unique-human/antispoof.md), [Uniqueness](https://docs.valyd.vip/verify/unique-human/face-uniqueness.md), and [Common errors](https://docs.valyd.vip/verify/unique-human/errors.md). (ID/KYC, face match, age, professional license, and location run only as workflow checks in a Reusable Verification session.)
- [Developer Portal](https://docs.valyd.vip/verify/console.md): Apps, API keys, workflows, webhooks, SSO. (Human-only UI steps.)
- [Node SDK](https://docs.valyd.vip/verify/sdk.md): Install/init @valyd/sdk, resources, types, error handling, Express webhook handler.
- [Webhooks](https://docs.valyd.vip/verify/webhooks.md): Register a callback URL and verify HMAC-SHA256 signatures over the raw request body.
- [Statuses & decisioning](https://docs.valyd.vip/verify/statuses.md): Every session/check status, what it means, and how to act on it — plus `verify.sessions.decision()`.
- [Checks reference](https://docs.valyd.vip/verify/types.md): Every workflow check — ID/KYC, liveness, face match, age bands, professional license, face uniqueness, location.
- [Consent & data access](https://docs.valyd.vip/verify/data-sharing.md): What the user consents to share, what your app receives (proofs, never raw PII), and what stays with Valyd.

## Verification APIs — API Reference

- [API Reference](https://docs.valyd.vip/verify/api-reference.md): Sessions, Workflows, the Unique Human API checks, Decision, and Errors & rate limits — all driven through the SDK with your App key.

## API specs (OpenAPI 3.1)

- [Valyd ID OpenAPI](https://docs.valyd.vip/openapi/valyd-id.json): OIDC connect and account-resource endpoints, schemas, auth, and errors.
- [Verification APIs OpenAPI](https://docs.valyd.vip/openapi/valyd-verify.json): Sessions, the Unique Human API checks, credentials, and the verification webhook (HMAC-SHA256). Use for SDK/codegen.

## Downloads & tooling

- [Postman collection](https://docs.valyd.vip/valyd-postman-collection.json): Importable collection of the Valyd ID API requests.
- [Node SDK starter](https://docs.valyd.vip/downloads/valyd-sdk-starter.zip): Starter scaffold for integrating Valyd.


## Developer portal — accounts, organizations & teams

- [Developer accounts & sign-in](https://docs.valyd.vip/docs/developer-accounts.md): Passwordless sign-in (emailed magic link or face / Connect with Valyd — there is NO password), connecting a Valyd face identity to an email-only account, and how one identity can own several console accounts (one per company) with an account switcher. Human-only portal actions.
- [Organizations & teams](https://docs.valyd.vip/docs/organizations.md): Individual vs organization accounts, the owner/developer/member roles, shared apps, public vs private apps, adding a workforce by face, and one-account billing.

## Human-only steps (an agent must pause and request these)

- Sign up for a Valyd account and log in to the Developer Portal: https://dev.valyd.vip (no KYC required).
- Create a Valyd ID project; copy `client_id` and `client_secret` (secret shown once — regenerate if lost).
- Register the exact redirect/callback URL on the project (must match what you send; no trailing slash).
- Sign in to the Developer Portal (https://dev.valyd.vip) with Valyd SSO; copy the App API key (shown once).
- Create a Verify workflow and copy its `workflow_id`; set the webhook URL and signing secret.