/ INTEGRATIONSConnectivity interface

Integrate KYA into your platform.

Whether you run an agent operator stack or a merchant checkout, KYA gives you a single REST surface to resolve agent identity, read the operator's posted attestations, and return a recommendation your authorization path can act on inline.

/ 01Protocol lifecycle

From agent registration to inline verdict.

Three stages, three endpoint paths. Every example below is what the current API accepts — no invented trust scores, no fictional response fields.

/ 01Step 01

Agent registration

Operators complete KYB and register each agent against their operator record. The handler requires name, model_provider, deployment_type, agent_type, and operator_id (the UUID returned by GET /api/v1/operators/me). Capability caps and MCC rules are attached separately via the attestation routes.

POST /api/v1/agents
Authorization: Bearer KYA_KEY

{
  "name":            "shopping-agent-v2",
  "model_provider":  "openai",
  "deployment_type": "cloud",
  "agent_type":      "assistant",
  "operator_id":     "5f3c8a2b-1234-4abc-9def-abc123def456"
}
/ 02Step 02

Trace generation

At runtime the agent mints an X-KYA-Trace-ID — a short-lived, Ed25519-signed JWT bound to a specific audience, scope, and spend limit. The operator-side call passes the authorizing principal as a hash, not in cleartext.

POST /api/v1/trace/generate
Authorization: Bearer KYA_KEY

{
  "agent_kya_id":     "kya_agent_01HX5N...",
  "audience":         "checkout.merchant.com",
  "scope":            ["purchase"],
  "max_amount_cents": 500000,
  "principal_hash":   "sha256:2f1b..."
}
/ 03Step 03

Edge verification

On the checkout path, your backend calls /api/v1/verify with the agent KYA ID and transaction context. The response returns the recommendation (accept / review / decline), the reasons behind it, and a verification_id for your order record.

POST /api/v1/verify
Authorization: Bearer KYA_KEY

{
  "kya_id": "kya_agent_01HX5N...",
  "transaction_context": {
    "amount_cents": 4999,
    "currency":     "USD"
  }
}
/ 02Two sides of the handshake

Build as an operator. Or plug in as a merchant.

For operators

Register agents. Manage mandate.

Register and manage your agent fleet programmatically. Bind each agent to a spending cap, MCC allow-list, and velocity ceiling the principal has mandated.

  • Agent registration + KYB
  • Mandate attachment + revocation
  • Trace JWT generation
  • CLI: @knowyouragent/cli
Operator docs
For merchants

One verification call on the auth path.

Verify every agent interaction directly inside your checkout flow. The verdict arrives inline with the authorization decision — no separate service to orchestrate.

  • Shopify app (in active development)
  • REST verification surface
  • Pre-dispute side-channel
  • Evidence log retrieval
Merchant path
/ 03FAQ

Integration questions.

How do I integrate KYA into my checkout?+

Start with /api/v1/verify alongside your existing authorization. Your backend POSTs the agent's KYA ID and transaction context to /api/v1/verify and acts on the recommendation field; if you enforce signed traces at checkout, add /api/v1/checkout/sessions alongside it. No processor swap, no cart platform changes.

Does KYA work with Shopify and WooCommerce?+

A Shopify app is in active development; WooCommerce and custom-stack integrations use the REST surfaces. Both approaches sit on the authorization path so the verdict arrives inline.

What languages does KYA support?+

KYA exposes a stable REST surface that works with any language that speaks HTTP — Python requests, Node fetch, Go net/http, curl. Typed SDKs are on the roadmap; the CLI (@knowyouragent/cli) ships today.

Start building

Wire KYA into your stack today.

Read the protocol docs, or talk to a solutions engineer about your specific checkout stack.