Agent integration guide

How an AI agent integrates Valyd: read the machine-readable docs, ask the developer the right questions, pick the product, and call the APIs. (Prefer callable tools instead? See the Valyd MCP server.)

Valyd has two products:

Unique Human API — API-key-only: prove a person is live and/or unique. No login, the result returns to the caller, nothing saved to an account.
Reusable Verification — the user connects with Valyd (standard OIDC), you read their verified data, run a configured workflow on a verification session, and read the decision. Passed proofs save to the user’s Valyd ID and are reusable.

Integration decision flow (start here)

If you’re an agent scaffolding this in a tool like Lovable, Cursor, or Claude Code: ASK the developer the questions below BEFORE writing code. Each answer pins one product, one credential, and one doc page to fetch and follow. Invent nothing — the credentials, endpoints, and page names here all come from the docs those pages link to.

Ask, in order:

1. Do you already have an app, or are you starting fresh?

Context only — it tells you where the “Connect with Valyd” button and the keys go. No branch; keep going.

2. Do you have — or want — an organization (a team/workforce you onboard and control)?

Yes, and you want to control members — add people, decide who can log in, assign roles → Organizations path. You onboard members by face-activation; they then sign in with Connect with Valyd. Roles are owner / admin / developer / member. Track exactly who logged in via the valyd_org_member_id claim (its value is that member’s vmem_… id) on the OIDC userinfo response and ID token. Billing is unlimited verifications on a per-active-member monthly plan (a member is billable only once they scan their face; 14-day trial first; current price at /docs/organizations/billing). → Credential: client_id + client_secret (Connect with Valyd) plus the Members API (headers X-Client-Id / X-Client-Secret, server-side only). → Fetch Organizations.
No org / no member control → continue.

3. Do you just need to know a person is live and/or unique, with only an API key?

No login, no Valyd account involved, the result returns to your system, nothing is saved. → Unique Human API:

Create a session with no user token for a workflow containing the checks, redirect the person to Valyd’s verification page, and read the decision:

Liveness (anti-spoof — flags photos, masks, replays, deepfakes): the antispoof check — see Liveness.
Uniqueness (one-person-one-account dedup — a stable valyd_ uuid per face): the face_uniqueness check — see Uniqueness.

verify.sessions.create({ workflowId, redirectUrl }) → session.url → verify.sessions.decision(sessionId).

→ Credential: SDK App key + workflow_id. → Fetch Unique Human API.

4. Do you need reusable verified identity — KYC, ID, face match, age, license, location?

Or want to read proofs the user’s account already holds, or save new proofs to it? → Reusable Verification — one journey:

Connect with Valyd (standard OIDC) — the user connects and you get their valyd_access_token. → Authentication
Read verified data — proofs (id_verified, age bands, licenses) from the account, free and instant, via the Account API. → With the user’s token
Run a configured workflow on a verification session — verify.sessions.create({ workflowId, valydAccessToken, redirectUrl }). Every check is available here: ID/KYC, liveness, face match, age, professional license, face uniqueness, location. → Workflows · Run a verification
Get the decision — verify.sessions.decision() or a signed webhook. → Statuses · Webhooks

Passed proofs save to the user’s Valyd ID (reusable across your apps) while the raw identity data stays encrypted with Valyd — you get the decision plus reusable proofs, never raw PII. → Credential: client_id + client_secret (connect) + SDK App key + workflowId + the user’s valyd_access_token. → Fetch Reusable Verification.

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 (a connected user’s verification session created through the SDK). The Unique Human API covers liveness and uniqueness only, with no account.

Connect with Valyd is standard OIDC and can also serve as your app’s sign-in on its own — connect the user, run no check. It is part of Reusable Verification, not a separate product. → Credential: client_id + client_secret. → Fetch Authentication.

Then clarify (as relevant)

Once the product is set, ask whichever of these apply and fetch the named page:

Which workflow checks do you need? ID / KYC, face match, age (returns age bands like is_18_plus — never the DOB), professional license, liveness, face uniqueness, and location / EVV presence all run as workflow checks in a Reusable Verification session. → Checks reference
Reusable identity (KYC-reuse)? Save a passed check as a proof so you never re-verify that person again — that’s Reusable Verification, needs the user’s valyd_access_token. A Unique Human API call saves nothing. → With the user’s token
How should results be delivered? Async signed webhook, or read the decision from the SDK (verify.sessions.decision() — both products run on sessions; a Unique Human session simply has no user token). → Webhooks · Statuses
Do you need RAW identity data (DOB, document number, address)? That requires the explicit consent flow — the user approves on their own device; otherwise you only ever receive proofs / verified-status. → Request user data
Which connect scopes? profile (legal name, country, verified status), verifications (proofs / badges), email, doctor_license. → Scopes
Professional license check? A workflow check in a Reusable Verification session — the name comes from the account and the verified badge saves to their Valyd ID. → Reusable Verification
Drop-in button or your own OIDC library? The “Connect with Valyd” button (Valyd ID docs) or any OIDC library via discovery (OIDC).
Where do the credentials come from? (important for agents) A human must create the app and keys in the Developer Portal (https://dev.valyd.work ) — an agent cannot mint client_id / client_secret / API key / workflow_id. Pause and ask the developer for them; never guess. → Dev portal setup
Billing model? Organization = unlimited verifications on a per-active-member monthly plan (a member becomes active, and billing starts, the moment they face-scan; current price at /docs/organizations/billing); non-org = pay per check. → Organizations

Agents scaffolding in a tool like Lovable/Cursor: ASK these questions before writing code; then fetch the named page’s .md and follow it. The exact .md fetch URL for each page is listed in llms.txt (e.g. .../docs/organizations.md, .../docs/user-token.md, .../verifications/unique-human.md, .../verifications/quickstart.md) — see Step 1.

Step 1 — Read `llms.txt` first


curl -sL https://docs.valyd.work/llms.txt

One fetch gives the agent the full docs hierarchy, base URLs, credential rules, and links to every page as clean Markdown. Fetch individual .md pages on demand rather than loading the full corpus, unless you need everything — then use llms-full.txt. The OpenAPI 3.1 specs (Valyd ID · Verification APIs ) and the Postman collection are listed on the agent-readable docs page.

Step 2 — Pick a product

Unique Human API (SDK App key, no user account). To prove a person is live and/or unique: create a session with no user token for a workflow containing the liveness / uniqueness checks (verify.sessions.create({ workflowId, redirectUrl })), redirect the person to Valyd’s verification page, and read the verdict from verify.sessions.decision(). Nothing is saved to a Valyd account, and the result is yours to manage and protect. Start at the Unique Human API.

Reusable Verification (a connected user’s token). The user connects with Valyd (OAuth 2.0 / OIDC); your agent acts with their access token. Read the proofs their Valyd ID already holds (id_verified, age bands, licenses) instead of re-verifying, and run a configured workflow — ID/KYC, face match, age, license, liveness, uniqueness, location — on a verification session with the token attached; the passed proof saves to their account for reuse everywhere and the raw identity data stays encrypted with Valyd. Start at Reusable Verification and the Valyd ID docs. Need raw personal data? Use the human-in-the-loop consent flow — the user approves the exact fields in their Valyd app and the values arrive sealed to your key.

Step 3 — Call the APIs

Follow the pages llms.txt points to. Two golden rules keep the products straight:

The two golden rules

The Account API never runs a check — a user token only reads proofs the account already holds.
A check never touches an account unless the user’s token is attached to the call — API-key-only checks return results to you and save nothing to any Valyd ID.

Notes for agents

Credentials cannot be created via API. Pause and ask a human to supply client_id, client_secret, and VALYD_API_KEY before making auth calls.
Token exchange and webhook signature verification must run server-side — never expose client_secret to a browser.
Prefer the clean .md URLs listed in llms.txt over scraping HTML pages.
Prefer proofs over raw data where they suffice — request is_18_plus, not dob.

Prefer tools over raw HTTP? Connect the MCP server instead.