Let your agent guide your KYB setup

Paste this into your coding agent. It will check the current connection before asking you to configure anything, then guide one sandbox business verification from discovery through report retrieval.

Paste this to your agent

agent-guide.md is a focused operating guide for this early access workflow. It covers connection checks, OAuth, business search, optional candidate confirmation, verification, non-terminal results, and report retrieval.

Review the KYB workflow and response fields →

The MCP endpoint

One hosted endpoint, spoken over MCP streamable HTTP. Any MCP-compatible client or agent framework connects to the same URL - one integration for your whole fleet.

Endpoint

Try synthetic data without signing in

Use https://mcp.trulioo.com/mock/mcp for anonymous protocol testing. In a connection tester, enter that URL and leave Auth Header empty. This endpoint returns synthetic data and has a limited feature set. Call trulioo_health, confirm mode: sandbox, then read trulioo_capabilities before choosing a workflow.

/mcp remains the authenticated endpoint for installed plugins. Choose Sandbox during OAuth to evaluate it without Trulioo API credentials. The host root is a documentation page, not an MCP transport. The existing /sandbox/mcp alias still requires OAuth and does not bypass authentication or select a mode.

Connection troubleshooting

Keep bearer tokens and Trulioo API secrets out of prompts, screenshots, logs, and committed configuration. An MCP access token is distinct from your Trulioo API client secret; use the approved bootstrap below for autonomous live integrations.

For hosted actions that require review, tool approval in the client alone is insufficient. The server requires an actor-bound session and the reviewed Trust Workspace flow. Mock and shared sandbox credentials cannot authorize those actions.

Authentication

/mcp requires an access token. Start with the sandbox connection to validate your KYB workflow. When your account is approved for live use, bootstrap a live token with your Trulioo client credentials.

Sandbox connection

Claude Code, Cursor, Codex, and ChatGPT connect through OAuth 2.1 + PKCE. Clients with private URI callbacks, including Cursor, need a local bridge with a supported callback. OAuth-capable clients manage the flow:

1. Add https://mcp.trulioo.com/mcp to the client.
2. The client discovers Trulioo authorization and opens the consent flow.
3. Choose sandbox.
4. The client initializes the MCP session and loads the tools available to that connection.

Start in sandbox

Sandbox uses the same endpoint and tool schemas as live access. It is unbilled and intended for testing the full integration before you work with production data. Sandbox results include a test_mode marker so your application can identify them.

Live integration with client credentials

For an approved live account, store the Trulioo client_id and client_secret in your secret manager or environment. Send them only to the token bootstrap endpoint over TLS.

Request an MCP access token

Response

The bootstrap validates the credentials with Trulioo, holds the upstream credential server-side, and returns a short-lived MCP access token. Store the returned access_token in TOKEN; the Raw JSON-RPC client setup below shows the complete initialization sequence.

• Never send client_secret to /mcp, place it in a URL, or log it.
• The bootstrap does not return a refresh token. Re-run the bootstrap when the MCP access token expires or the server returns 401.
• 401 invalid_client means the credentials were malformed or rejected. Retry only after checking the credential configuration.
• If Trulioo authentication is temporarily unavailable, retry the bootstrap with bounded backoff.

Usage limits

Usage limits apply and may change during early access. If a result includes retry_after_seconds, wait for that interval before retrying. Contact Trulioo before a production-scale rollout so limits can be reviewed for your use case.

Client setup

Pick your client and point it at the hosted endpoint. Use its OAuth flow for sandbox. For live use, the client must support sending the bearer token returned by the client-credentials bootstrap.

KYB tools reference

Tools reference

The KYB surface is a typed sequence: discover the business, resolve ambiguity, verify it, poll when needed, and fetch the report. tools/list remains the authority for the tools available to your account.

Every capability is a typed, discoverable MCP tool - schema-enforced inputs, structured results agents branch on, and no raw passthrough - a tool that is not on your connection is not reachable by another route. A default progressive connection exposes 57 addressable entries: 18 resident tools and 39 deferred product capabilities. The product contract is 55 tools because two resident entries are progressive-only routing tools. Per-account families change the enabled set. The exact resident set is what tools/list returns for your connection, so discover it rather than hardcoding this list.

Example: call a tool over JSON-RPC

Both headers are required: $TOKEN from Authentication, and $SID from the initialize handshake - see Raw JSON-RPC under Client setup.

KYB workflow and responses

Identity & business verification

Result contracts

Tools return structured results an agent can branch on directly - not prose to parse.

kyb_verify (terminal shape)

kyc_verify (shape)

• Errors are results, not exceptions. A failed upstream comes back as a typed result the agent can reason about, not a thrown error that ends the run.
• Circuit breaker per upstream. Each verification surface has its own breaker, so one degraded provider does not take down the others.
• Async is explicit. is_terminal:false tells the agent to poll rather than assume completion. A long-running operation returns a continuation to poll; exhausting an approved poll budget requires review rather than an unbounded loop.

Give an agent an identity

Any agent can claim any name. Know Your Agent proves the real organization behind an agent and issues a signed, scoped, revocable credential - the Digital Agent Profile (DAP) - that anyone can verify. It rides in the agent's A2A card, so trust travels with the agent.

1. Verify the organization. KYC/KYB + sanctions on the accountable owner behind the agent.
2. Register the agent. The agent presents its own Ed25519 key; that key is the identity anchor. A build fingerprint binds the credential to this exact agent.
3. Sign a scoped mandate. kya_issue_mandate mints a short-lived, least-privilege attestation for named scopes (e.g. purchase), signed by identity.trulioo.com.
4. Publish it. The attestation attaches to your A2A card under capabilities.extensions[] (uri https://identity.trulioo.com/a2a/kya/v1) and is anchored in a tamper-evident log.

The KYA extension on an A2A agent card

How anyone verifies it →  ·  Do it in the portal →

Why agent trust has layers

"Verified" is not one thing. A DAP asserts a stack of independent facts, and a relying party checks the layers its risk calls for. Knowing the layers tells you exactly what a profile does - and does not - prove.

1. Identity anchor. The agent holds its own key. Everything else binds to that key, so the profile is about this agent, not a name it typed.
2. Integrity & provenance. A build fingerprint binds the credential to the exact code. Change the code and the fingerprint changes - forcing re-attestation.
3. Authenticity of use. A possession proof shows the party presenting the card actually controls the anchor key - not a copied card.
4. Origin & accountability. KYC/KYB ties the agent to a real, sanctions-screened organization, and every issuance is anchored in a tamper-evident log.

This matters to your company directly: it is what lets you (or your customers) accept an agent's action with a known, accountable party behind it - and decline or step up when a layer is missing. The full trust model →

Verify an agent (DAP)

Verification is the critical path: a system deciding whether to trust an inbound agent confirms its Digital Agent Profile and attestation before acting. Verify through MCP; the issuer also publishes the two keyless, public primitives so any party can check a profile with no account.

Try it live

Drive the mint-then-verify lifecycle end to end. This simulation runs entirely in your browser - no network calls. Mint on the left; verify the same agent on the right.

In an agent (recommended)

Call kya_verify_agent with the agent's card - it validates the signature, fingerprint, expiry and sanctions, and returns the Verified-by-Trulioo record. Add a requested_action to check it against the signed scope in the same step. This is the integration path; the KYA verification logic lives behind MCP, not a public write API.

Verify over MCP

$TOKEN comes from Authentication and $SID from the initialize handshake. If you only need to check a profile and not run a verification, the public keyless lookup below needs neither.

Public, keyless lookup (for any verifier)

The issuer publishes two public primitives at https://identity.trulioo.com so a relying party that isn't running an MCP client can still confirm a profile without an account:

• GET /kya/attestation/{dap} - look up an agent's current standing by its Digital Agent Profile (the "anyone can check" path).
• GET /.well-known/jwks.json - the issuer's signing keys (rotation-aware) to verify an attestation JWS yourself.

What a verifier checks: the JWS signature against the pinned issuer key by kid (the algorithm is pinned from the resolved key, never read from the token header - blocks alg:none and alg-confusion); the fingerprint against the agent's own key + card; the exp (short-lived, re-attested on change); verified; assurance.trust_tier against your own minimum; and the signed allowed_scopes. Scopes are signed and auditable but enforced by you, the relying party.

The DAP wire schema (ats-v2)

A Digital Agent Profile is a conformant SD-JWT-VC (typ: dc+sd-jwt) carrying a vct of https://identity.trulioo.com/vct/agent-profile.1. A passport core is inline - a KYB-verified operator and a composite assurance grade - while the identity, mandate, status and behavior objects are referenced and dereferenced independently. This is the exact record the KYA card flips to; the full JSON Schema is ats-v2-dap.schema.json (governed by ADR-P-022).

DAP 2.0 presentation (public-discovery profile)

Two profiles. Public discovery reveals agent_id/build_id inline (shown above). Pairwise withholds them via SD-JWT selective disclosure and substitutes a per-relying-party sub alias, so a profile isn't linkable across verifiers. The variant is chosen by the agent's exposure mode - never a caller flag - so an agent can't be tricked into over-disclosing.

How the DAP projects onto each rail

One DAP, issued once, is projected into each protocol's native shape - KYA proves who is accountable; the rail carries and authenticates the transaction. The mapping below is what actually travels on each rail and which DAP claim the verifier reads.

Drop-in "Verified" badge

Prefer not to build the UI? Embed the same <trulioo-verified> element Trulioo runs on its own surfaces. It runs the live attestation lookup itself, stays hidden until the agent verifies, and opens the full Digital Agent Profile on click - Organization, Issuer, DAP, verified-as-of, sanctions, attestations, scopes, and a link into the transparency log. One framework-agnostic custom element; no build step. It's live in the hero of the sibling Know Your Agent page.

Embed it

Orchestration patterns

The tools are typed and composable, so an agent chains them mid-task and branches on each result. The examples below show how to combine the raw tools.

KYB due diligence - discover, verify, screen

Pattern 2 - Onboard a business, then screen it

Find the business, confirm the correct candidate, verify it, and branch on the typed result.

Full tool reference →  ·  Result contracts →

Security & honest limits

• Schema-enforced inputs. Every tool validates its arguments (additionalProperties: false), so malformed or injected calls are rejected before reaching an upstream.
• Prompt-injection resistance. Tools act only on their typed arguments; free-text in a document or field is data, never an instruction to the server.
• Algorithm pinning. Attestation verification pins the algorithm from the resolved key (EdDSA / ES256 only) - alg:none and alg-confusion attacks are rejected.
• Honest limits. A DAP proves identity, integrity, scope and accountability - it does not authorize a payment or guarantee behavior. Scope enforcement is the relying party's; certified biometric liveness has a defined boundary. We surface dependencies we do not own.
• Governed surface. The verification agents and skills behind these tools are eval-gated and release-controlled - the same discipline you would apply to a compliance-critical dependency.

FAQ