Know Your Agent (KYA)

KYA (Know Your Agent) binds an AI agent's Ed25519 key to a person verified by Very with their palm, and gives a relying party, the service the agent calls, a verdict on each action the agent signs. The verdict covers the signature, the agent's status, the owner's standing with Very, replay, and, when the relying party asks for it, the owner's palm approval of that exact action.

What KYA proves#

When KYA returns valid: true for an action, all of this held at that moment:

• The agent signed this action. The action token verifies with the key registered for the agent, names your origin as its audience, carries the hash of the request you received, is within its lifetime, and was never accepted before.
• The agent is active. It is registered and not revoked.
• A verified person owns it. The owner completed the registration with a palm scan in the Very app, and is in good standing with Very now: not rejected, restricted or deleted, and still connected to KYA.
• The owner approved this action, when you ask for it. A human authorization is a fresh palm approval bound to this agent, this owner, your origin and this action, and it works once.

What KYA does not tell you:

• Who the owner is. You get KYA's own owner id, never a Very user id or a name. The owner id is pseudonymous, not anonymous: it is the same for every agent of that owner, so it links them, and it can identify a person when combined with other data. Handle it like any other user identifier.
• That the owner is present at each action. Only a human authorization says the owner approved a specific action.
• What the agent will do. KYA vouches for who stands behind the agent, not for its behavior.

Owners and agents#

• Owner: a person with the Very app who has verified with their palm. One owner can hold many agents.
• Agent: named by a device_id it chooses, and holding one Ed25519 key. The key's id, kid, is its RFC 7638 JWK thumbprint, which is also the keyid the agent uses for Web Bot Auth.
• One key per agent, used once. A key that was registered can never be registered again, even after revocation. A revoked agent's device_id cannot be reused either: start over with a new id and a new key.
• Revocation is permanent. The agent can revoke itself with its key, the owner can revoke one agent or all of theirs with a palm approval, and Very can revoke an agent.
• Owner standing is good, suspended (Very rejected, restricted or deleted the owner, or the owner disconnected KYA) or unknown (Very did not answer). Unlike a revocation, a suspension can end.

Approvals in the Very app#

Every palm ceremony is an approval the owner completes in the Very app. There is no browser redirect. KYA uses one flow for registering an agent, approving one action, and the owner revoking agents:

1. The call that starts the approval returns links.qr_url and links.app_link.
2. The owner scans the QR code with their phone, or opens the app link on the phone that has the Very app, and completes a palm scan.
3. The caller polls GET /v1/approvals/{approval_id} until the status is completed, failed or expired. Polling is also what completes the approval, so keep polling until it ends.

For an action approval and a revocation, only the owner's palm can complete it. For a registration, whoever completes it becomes the agent's owner, so show the link only to the person who should own the agent. Today the Very app shows "KYA by VeryAI" for every approval but not which operation it is, so tell the owner what they are approving when you show the code.

Relying parties#

A relying party is any service an agent calls: an API, a website, a marketplace. The verification endpoints need no account or API key. There are three ways to check an agent:

Gate on valid, and fail closed: when KYA answers 503, it could not check the owner's standing or its own records, and it does not vouch.

Tokens#

Every token in KYA is a compact JWS signed with EdDSA (Ed25519). The JOSE typ header tells them apart, and one must never be accepted in place of another.

KYA's signing keys are published at /.well-known/jwks.json under the API base URL.

Reverse CAPTCHA#

KYA also issues challenges that software solves in seconds and a person at a keyboard cannot finish within the time limit. Solving one earns a capability token. It shows that software solved a KYA challenge in time: not that an AI solved it, and not whose agent it is. See Reverse CAPTCHA.

URLs#

Security notes#

• Private key: stays on the agent. KYA only ever receives the public key and signatures.
• Approval links and ids: give the QR code or app link only to the owner. The approval id is a bearer handle: anyone who holds it can read the result, including a human authorization.
• Your view of the request: as a relying party, send KYA your own origin and your own hash of the request you received, never values taken from the token.

Ready to integrate? See the Integration Guide, or the API Reference for every endpoint.