KYA API Reference

Base URL: https://api.very.org/kya (staging: https://api.stg.very.org/kya). Paths below are relative to it. The same API is published as an OpenAPI 3.1 spec at /openapi.yaml.

Conventions#

• No API key. The endpoints are public and send Access-Control-Allow-Origin: *. Agents prove themselves with signatures; owners with a palm scan in the Very app.
• JSON in snake_case. A request body is one JSON object of at most 64 KiB (413 request_too_large beyond). Unknown fields are ignored.
• Encodings. public_key and signatures accept base64 or base64url. Hashes and token ids are base64url without padding (padding is tolerated).
• Errors are {"error": "<code>", "message": "<text>"}. The code is stable; the message is for people. 400 invalid_request is a malformed request, 503 means KYA or Very could not answer, and 500 internal is unexpected.
• Verdicts are not errors. actions/verify, signatures/verify and challenges/verify answer 200 for every refusal, with the reason in the body.

{
  "error": "agent_not_found",
  "message": "no agent with this device id"
}

Endpoints#

POST /v1/registrations#

Register an agent. The agent proves it holds the private key with a kya-register:v1 proof, and KYA starts a registration approval. Whoever completes it in the Very app becomes the agent's owner. A key is single use: once registered, revoked or not, it can never be registered again.

Request body#

POST /kya/v1/registrations
Content-Type: application/json

{
  "device_id": "my-agent-01",
  "public_key": "MCowBQYDK2VwAyEA...",
  "proof": {
    "message": "kya-register:v1:my-agent-01:<kid>:1793803667000",
    "signature": "<base64url Ed25519 signature>",
    "timestamp": 1793803667000
  }
}

Response (201)#

An Approval of kind registration. It expires after 15 minutes.

{
  "approval_id": "9-ViRBp9vndJpqSilQbwILNR2Y5lG9rFNgHfalNdvYk",
  "kind": "registration",
  "status": "pending",
  "device_id": "my-agent-01",
  "expires_at": "2026-11-04T15:02:46.214189Z",
  "links": {
    "qr_url": "https://connect.very.org/download?action=oauth&clientId=...&key=...&requestId=...&sessionId=...",
    "app_link": "veros://scan/?action=oauth&clientId=...&key=...&requestId=...&sessionId=..."
  }
}

Errors#

POST /v1/approvals#

Ask the agent's owner to approve one action (step-up). Only the agent itself can start an action approval, with a kya-approve:v2 proof bound to what is approved. Very matches only the owner's palm. On completion, result.authorization is a kya-authorization+jwt bound to the agent, its owner, audience and action_hash. The agent sends it to the relying party with the action token, and the relying party passes it to actions/verify as human_authorization.

Request body#

binding is base64url (no padding) of SHA-256 over u32be(len(audience)) || audience || action_hash_digest || u32be(len(action_description)) || action_description. Lengths are 4-byte big-endian byte counts, strings are UTF-8, action_hash_digest is the 32 raw digest bytes, and an absent description is empty. So the proof covers exactly what the owner is asked to approve. See the test vector.

POST /kya/v1/approvals
Content-Type: application/json

{
  "device_id": "my-agent-01",
  "audience": "https://shop.example.com",
  "action_hash": "<base64url SHA-256 of the action>",
  "action_description": "Order 1 x A-100",
  "proof": {
    "message": "kya-approve:v2:my-agent-01:<kid>:1793803667000:<binding>",
    "signature": "<base64url Ed25519 signature>",
    "timestamp": 1793803667000
  }
}

Response (201)#

An Approval of kind action. It expires after 5 minutes. When it completes, result.authorization is valid for 5 minutes and works once.

Errors#

GET /v1/approvals/{approval_id}#

Poll an approval about every 2 seconds until status is no longer pending. Polling is what completes it: while it is pending, a poll reads the Very app's answer and acts on it. The approval id is a bearer handle: anyone who holds it can read the result. Responses are Cache-Control: no-store.

Response (200)#

An Approval.

Errors#

GET /v1/agents/{device_id}#

An agent's public entry. This is a lookup, not a decision: if Very does not answer for the owner, owner_standing is unknown rather than an error.

Response (200)#

An Agent.

{
  "device_id": "my-agent-01",
  "kid": "<kid>",
  "public_key": "MCowBQYDK2VwAyEA...",
  "status": "active",
  "owner_id": "3f2c9a8e-5d41-4b7a-9c3e-1a2b3c4d5e6f",
  "owner_standing": "good",
  "registered_at": "2026-11-04T14:49:10.52Z"
}

Errors#

GET /v1/keys/{kid}#

The same entry, looked up by the agent's key id: the RFC 7638 JWK thumbprint of its key, base64url(SHA-256({"crv":"Ed25519","kty":"OKP","x":"<base64url key>"})). It is the keyid of the agent's Web Bot Auth signatures. Same response and errors as GET /v1/agents/{device_id}, with agent_not_found for an unknown key id.

POST /v1/agents/{device_id}/revoke#

The agent revokes itself, at once, with a proof signing kya-revoke:v1:<device_id>:<kid>:<timestamp_ms>. It is permanent: the key and the device_id can never be registered again. Repeating it returns the original revocation.

Request body#

Response (200)#

The revoked Agent, with status revoked, revoked_at and revoked_by. owner_standing is not looked up here and reads unknown.

Errors#

POST /v1/agents/{device_id}/owner-revocations#

Start an approval for the owner to revoke this agent (scope: "agent") or every agent they hold (scope: "all"). Anyone can start it, since the owner may have lost the agent; only the owner's palm completes it. Any other palm fails the approval with owner_mismatch. scope: "all" can be started from any of the owner's agents, revoked or not.

Request body#

Response (201)#

An Approval of kind revoke_agent or revoke_all. It expires after 5 minutes. When it completes, result.revoked_device_ids lists the agents it revoked.

Errors#

POST /v1/actions/verify#

The relying party forwards the agent's action token with its own view of the request: expected_aud (its origin) and expected_action_hash (base64url(SHA-256(JCS(action))), recomputed from the request it received). KYA never takes either from the token. Keys come only from KYA's registry, by the token's iss and kid.

Request body#

POST /kya/v1/actions/verify
Content-Type: application/json

{
  "action_token": "<kya-action+jwt from the Kya-Action header>",
  "expected_aud": "https://shop.example.com",
  "expected_action_hash": "<your base64url SHA-256 of the action>",
  "human_authorization": "<kya-authorization+jwt from the Kya-Authorization header>",
  "require_human_authorization": true
}

The action token is a compact JWS of at most 4096 bytes:

• Header: {"alg":"EdDSA","typ":"kya-action+jwt","kid":"<RFC 7638 thumbprint>"}. The jwk, jku, x5u, x5c, x5t, x5t#S256 and crit members are refused.
• Claims: iss (the device id), aud (a string, or an array of exactly one), iat and exp (integer seconds, exp at most 300 s after iat; 60 s of skew allowed on iat only), optional nbf, jti (16 to 64 random bytes, base64url), action_hash, optional action_type.

Response (200)#

An ActionVerdict. Gate on valid. The jti, and any human authorization presented, are spent only when everything else passed. A human authorization found valid is spent even when you did not require one: it authorizes exactly one action.

{
  "valid": true,
  "signature_verified": true,
  "device_id": "my-agent-01",
  "kid": "<kid>",
  "agent_status": "active",
  "owner_id": "3f2c9a8e-5d41-4b7a-9c3e-1a2b3c4d5e6f",
  "owner_standing": "good",
  "aud": "https://shop.example.com",
  "action_hash": "<base64url>",
  "action_type": "order",
  "jti": "<base64url>",
  "replay": "fresh",
  "human_authorization": {
    "required": true,
    "present": true,
    "valid": true,
    "consumed": true,
    "device_match": true,
    "owner_match": true,
    "aud_match": true,
    "action_hash_match": true,
    "exp": 1793803967
  },
  "reason_codes": [],
  "verified_at": "2026-11-04T14:50:01.12Z",
  "receipt": "<kya-receipt+jwt>"
}

Errors#

POST /v1/signatures/verify#

Checks a detached Ed25519 signature over the UTF-8 bytes of message with the registered key of the agent named by device_id or kid, and that the agent is active and its owner in good standing. It binds nothing: no audience, no action, no replay check. The message and its freshness are yours: sign a nonce you chose. To gate an action, use actions/verify. Messages starting with kya- are KYA's own proofs and are refused (reserved_message).

Request body#

POST /kya/v1/signatures/verify
Content-Type: application/json

{
  "kid": "<kid>",
  "message": "login:3q2-7wQ8Zc1nHk0yS0pX2A",
  "signature": "<base64url Ed25519 signature>"
}

Response (200)#

A SignatureVerdict. Gate on valid. This one is for a key that is not registered:

{
  "valid": false,
  "signature_verified": false,
  "device_id": null,
  "kid": null,
  "agent_status": "unregistered",
  "owner_id": null,
  "owner_standing": "unknown",
  "reason_codes": ["agent_unregistered"],
  "verified_at": "2026-11-04T14:47:47.16Z"
}

Errors#

POST /v1/challenges#

Get a reverse-CAPTCHA challenge. The body is optional: {"type": "byte_transform" | "constrained_gen" | "structured_extraction"}, or no type for a random one. Each challenge allows one attempt at challenges/verify.

Response (200)#

{
  "challenge_id": "Jb8-NAN-j9pH95s8",
  "challenge_type": "constrained_gen",
  "difficulty": "medium",
  "payload": {
    "topic": "electric circuits",
    "lines": 3,
    "ascii_target": 341,
    "word_count": 15,
    "difficulty": "medium"
  },
  "token": "<opaque>",
  "expires_at": 1793803697,
  "time_limit_secs": 20
}

Errors: 400 invalid_request for an unknown type, 503 unavailable.

POST /v1/challenges/verify#

Submit a solution: {"token": "<from the challenge>", "solution": "<string>"}. On success, capability_token is a kya-capability+jwt valid for one hour. It says a KYA challenge was solved solve_time_ms after it was issued, faster than a person could: automation, not necessarily a language model. It names no agent and no owner. A relying party verifies it offline with the JWKS, and may keep its jti until exp to accept each token once.

Response (200)#

{
  "success": true,
  "challenge_type": "byte_transform",
  "solve_time_ms": 109,
  "capability_token": "<kya-capability+jwt>"
}

Errors: 400 invalid_request when token or solution is missing, 503 unavailable.

POST /v1/demo/solve#

Used by KYA's demo: the demo's agent (a language model) attempts one of KYA's challenges, sent back exactly as issued, as {"token": "...", "payload": {...}}. It returns the model's answer, unverified; submit it to challenges/verify like any agent. One attempt per challenge, and rate limited.

Errors: 400 challenge_invalid or challenge_expired, 409 already_attempted, 429 rate_limited, 503 demo_solver_disabled or unavailable.

GET /.well-known/jwks.json#

KYA's Ed25519 signing keys, for verifying the tokens KYA issues. Served at https://api.very.org/kya/.well-known/jwks.json and cached for up to 5 minutes. Select the key by the token's kid.

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "mLp3FNp00Q_jxWUmwRvBS934T8ICZuZfzB2_jkQ0Sps",
      "kid": "o7ngBw4L5qoC04SCAXAbN9fe8cS85DHTYdBN8anlVM4",
      "use": "sig",
      "alg": "EdDSA"
    }
  ]
}

Objects#

Proof#

Approval#

// kind: registration
"result": {
  "agent": {
    "device_id": "my-agent-01",
    "kid": "<kid>",
    "owner_id": "3f2c9a8e-5d41-4b7a-9c3e-1a2b3c4d5e6f",
    "registered_at": "2026-11-04T14:49:10.52Z"
  }
}

// kind: action
"result": {
  "authorization": "<kya-authorization+jwt>",
  "authorization_expires_at": "2026-11-04T14:54:10.52Z"
}

// kind: revoke_agent or revoke_all
"result": {
  "revoked_device_ids": ["my-agent-01"]
}

Agent#

ActionVerdict#

SignatureVerdict#

valid, signature_verified, device_id, kid, agent_status, owner_id, owner_standing, reason_codes and verified_at, as in ActionVerdict. valid is true when the signature verifies, the agent is active and its owner is in good standing.

Reason codes#

The set is closed: you can switch on them.

Tokens KYA issues#

Signed with EdDSA by the key in the JWKS, with header {"alg":"EdDSA","typ":"<typ>","kid":"<KYA key id>"}. iss is the API base URL: https://api.very.org/kya (staging https://api.stg.very.org/kya). Check typ: one kind must never be accepted as another.