A machine-readable way for an API consumer to say who they are, and for an API provider to decide whether that is enough.
Important
Status: design. Nothing here is built. This document is the architecture agreed in api-evangelist/roadmap#110–#119, written down so it can be built against. No KYA record exists, no facet has been verified, no attestation has been issued, and no provider consumes this. Every version number below is a target, not a release. Do not cite this as a shipped capability.
Every API provider makes you fill in a signup form, because they need to know who you are before handing over a key. An AI agent cannot fill in a form. That is why agent onboarding is manual almost everywhere — not because the authentication is hard, but because the form is a data-collection instrument wearing an authentication costume. Remove the form and the provider loses the thing it actually wanted.
AOD is the provider saying what onboarding requires. KYA is the consumer saying who they are. The Directory is where they meet.
| piece | says | status |
|---|---|---|
| AOD — API Onboarding Descriptor | what this provider requires to onboard | shipped, live at /.well-known/api-onboarding |
| KYA — this document | who this consumer is, and what has been verified | design |
| Directory | issues attestations, holds the register, publishes the rules | design |
An agent builds a profile once — who runs it, how to reach them, what it is for, what it has done. We verify what we can and mark clearly what we could not. When the agent shows up at a new API, the provider gets those facts instead of a form.
We do not tell the provider whether to trust the agent. We tell them what is true, and they decide — using their own priorities, not ours.
- Not KYC. The name borrows the shape of a familiar idea. KYA is a brand, not a regulatory regime. It is not an anti-money-laundering control, carries no regulatory force, and satisfies no legal obligation. If it reads as compliance tooling, someone will rely on it as compliance tooling.
- Not a trust score. No allow/deny, no "verified safe" badge, no certification.
- Not a background check. It records how strongly a consumer is tied to a domain and what has been verified. It says nothing about intent or character.
- Not a gate the Directory operates. Providers decide. The Directory publishes facts and performs the arithmetic the provider asks for.
Every requirement below grounds in an existing IETF or OpenID standard. This work only composes and profiles them — the same posture as the API Authorization Profile.
| need | standard |
|---|---|
| find the API, the AS, and how it is protected | RFC 8615, RFC 9727, RFC 9264, RFC 8414, RFC 9728, OIDC Discovery |
| register with no human | RFC 7591, RFC 7592, Client ID Metadata Documents |
| third-party attestation at registration | RFC 7591 software_statement |
| prove the request | RFC 9421 HTTP Message Signatures, Web Bot Auth |
| bind the token to a key | DPoP (RFC 9449), mTLS (RFC 8705), private_key_jwt |
| obtain, exchange, attenuate a token | OAuth 2.0 / 2.1, PKCE, Token Exchange (RFC 8693), Transaction Tokens |
| pull a human in when required | CIBA |
| broadcast revocation | OpenID Shared Signals + CAEP |
| workload identity | WIMSE, SPIFFE |
| machine payment | x402 |
| harden all of it | FAPI |
The attestation slot already exists. RFC 7591 §2.3 defines software_statement as a signed JWT asserting metadata about a client "as a bundle", carrying an iss claim naming the attesting party. UK Open Banking uses exactly this. The Directory becomes a software-statement issuer, not a protocol author.
RFC 7591 also states the necessary caveat, and it fits rather than fights the design:
"the software statement is an item that is self-asserted by the client, even though its contents have been digitally signed... presentation of the software statement is not sufficient in most cases to fully identify a piece of client software."
Graded facts, not a verdict. The provider still decides.
| # | artifact | shape |
|---|---|---|
| 1 | KYA facet vocabulary | JSON Schema + vocabulary |
| 2 | SSA profile | a profile of RFC 7591 |
| 3 | Evaluation interface | OpenAPI |
| 4 | Consent & disclosure state | OpenAPI + vocabulary |
| 5 | Directory rules & eligibility | rules document + register API |
| — | account.requires |
one additive field on AOD |
One vocabulary, one profile, two small APIs, one rules document, one field.
Six, deliberately mirroring the six facets of the provider-side Kin Score.
| facet | analogue | example checks |
|---|---|---|
| Identity Anchor | identity document | Web Bot Auth key directory resolves and signature verifies · CIMD URL served · WIMSE/SPIFFE ID · verified domain control |
| Operator Accountability | beneficial owner | name · email graded free / company-domain / matching the anchor · security.txt or abuse contact · published terms · legal entity |
| Provenance & Attestation | source of the applicant | declared framework and model · source repository · signed releases · attestation evidence (TEE, supply chain) |
| Declared Intent | purpose of the relationship | stated purpose · requested vs actually used scopes · respects robots.txt / AIPREF / Content-Signals · rate discipline |
| Operating History | ongoing monitoring | tenure · volume in bands · scope drift · revocation history with stated basis · presence at more than one provider |
| Standing | source of funds | free vs paid · payment method verified · x402 capable · quota compliance |
| number | controlled by | direction |
|---|---|---|
| Disclosure | the consumer | monotonic — rises as they tell us more |
| Verification | the Directory | independent of disclosure |
Collapsing these would let a consumer who fills every field with unverified claims score like one with fewer verified facets. Presence is not provenance — a lesson the provider-side rubric had to learn in production, and one this rubric is born with.
| grade | meaning |
|---|---|
verified |
independently confirmed — DNS, signature, resolvable domain, payment rail |
asserted |
the consumer stated it; unchecked |
inherited |
from an already-evidenced source — an OAuth provider identity, or an operator domain already scored as a provider in the catalog |
absent |
not supplied |
inherited is the network effect. A consumer whose operator domain is already a scored provider arrives with evidence it did not have to re-establish.
AOD gains one additive, backward-compatible block:
"account": {
"requires": [
{ "facet": "identity_anchor", "grade": "verified" },
{ "facet": "operator_accountability.legal_entity", "grade": "verified" },
{ "facet": "operator_accountability.email", "grade": "verified",
"constraint": "company-domain" }
]
}Then:
- Consumer discovers a provider through the Directory
- Consumer reads the provider's AOD and its
requiresblock - Consumer compares against its own facet vector — before attempting anything
- Match → requests an SSA from the Directory carrying only the required facets → presents it at the provider's RFC 7591 endpoint → onboarded, no human
- No match → receives a precise list: which facet, at what grade. Actionable, not a rejection
agentPolicysays no → the consumer does not try, and neither side wastes a request
Step 4 makes GDPR data minimisation structural: the provider asked for three things and receives three things. Step 5 is what makes this a market rather than a gate.
Core — present in a transaction:
| actor | is | data-protection role |
|---|---|---|
| Consumer | the agent or application itself | not a data subject — software |
| Operator | the legal entity accountable for the Consumer | data subject; controller for Principal data |
| Principal | the end user the Consumer acts for | data subject |
| Provider | publishes the API; enrolled; maintains a Kin Score | recipient; controller of its own user data |
| Authorization Server | issues tokens; may or may not be the Provider | processor for the Provider |
| Intermediary | gateway, MCP host, broker acting for a Consumer | processor for the Operator |
Framework — make the scheme work:
| actor | is | data-protection role |
|---|---|---|
| Directory | register, attestation issuance, rules | controller of the KYA record |
| Attestation Source | verifies a facet — DNS, a CA, an edge bot verdict, an IdP | processor or independent controller |
| Settlement | the payment rail | independent controller |
| Conformance Body | certifies that an implementation conforms | — |
| Redress | handles disputes | — |
| Supervisor | a regulator. Slot, unfilled | supervisory authority |
Not public. Modelled on UK Open Banking, which gates twice — authorisation and directory enrolment.
| tier | who | sees |
|---|---|---|
| public | anyone | domain-anchored facts only: anchor type, tenure, volume band, revocation with basis |
| network | enrolled providers maintaining a Kin Score | the facet vector, at the grades the consumer consented to disclose |
| consumer | the consumer | everything held, plus who queried it and when |
Reciprocity: to read a consumer's facets, publish your own. Both sides legible in the same vocabulary.
This changes what the Kin Score is. Today it is observational — providers are measured whether they participate or not. As the key to a data service it is also a membership credential, which creates gaming pressure that has never existed. Consequences accepted deliberately: eligibility is a distinct check set testing recipient-safety, never a band threshold; refusals carry a stated basis and an appeal path.
The Directory is a data controller from the first record. Not a caveat — a build requirement.
Two data subjects, and the second is the one that gets missed: the Operator, and the Principal the consumer acts for. The consent chain runs Principal → Operator → Provider.
- Lawful basis: consent — granular per facet and per provider, withdrawable without losing the account, never bundled into signup terms
- Art. 15 access, including who queried and when · Art. 16 rectification, which re-grades the facet · Art. 17 erasure, working end to end before the first record exists · Art. 20 portability · Art. 21 withdrawal effective immediately
- Art. 30 records of processing · Art. 35 DPIA before launch — this is profiling feeding automated access decisions
- Art. 22 — the Directory returns arithmetic the provider specified over facts observed, never a decision; and the facet vector is fully visible to the consumer. Both are deliberate
- Purpose limitation — onboarding trust decisions only. KYA data is never enriched, never sold, never enters any research corpus
- Data minimisation — an SSA carries only the facets the provider's AOD declared
- Transfers — an EEA consumer's facets reaching a non-EEA provider needs a transfer basis; enrolment is therefore a contract
- CPRA — disclosure to providers may constitute "sharing" even with no money changing hands. Needs a determination and, if so, an opt-out that does not break the product
The audit log is a product surface, not a compliance export. "Which providers read my record, and when" satisfies Art. 15 and is the most trust-building thing the consumer surface can show.
apis.io is the Directory. It is also a Provider. Open Banking held those apart deliberately — OBIE is not a bank — and choosing differently carries obligations:
- The Directory role is defined abstractly here, always. A second directory must be implementable from this document alone
- apis.io enrols as a Provider under the same rules as everyone else, visible in the register like any other entry
- The rules bind the Directory. Versioned, dated, diffable
- Key material and the register sit in a trust domain separate from the apis.io application
- The conflict is published. Stating it is what makes it survivable
Licensing: code Apache-2.0, documents CC BY-NC-SA, per API Commons policy.
api-evangelist/roadmap — #110 is the index.
| #110 | Kin Score has two sides — Provider and Consumer |
| #111 | Consumer rubric v0.1 — facets, the two-number split, grading |
| #112 | KYA API — manage a record; evaluate with caller-supplied weights |
| #113 | The twelve actors |
| #114 | Protocol composition and the gap list |
| #115 | Directory eligibility and reciprocal access |
| #116 | GDPR/CCPA control set |
| #117 | account.requires — the AOD ↔ KYA handshake |
| #118 | apis.io as the Directory |
| #119 | KYA as a brand |
Underneath it, the protocol chain that makes autonomous onboarding possible at all: #103–#109.
- Does a Consumer need a role taxonomy the way a TPP is AISP / PISP / CBPII? A read-only search agent and one that transacts are different risk objects
- Does a consumer's record appear on the provider pages of providers it onboarded with? More useful, considerably bigger claim
- Does AOD
maturityneed a rung aboveself-serve— a stranger with a browser is not a stranger with no human at all — or is that a separate axis?