The seven roles

Vocabulary, not a specification. These names exist so that a sentence like “we attested this as Directory, having sourced it ourselves” is sayable — and so that when something goes wrong it is possible to say which role failed.

This describes a product, not a standard. APIs.io does not require anyone else to implement these roles, and nothing here obliges a third party. What it does oblige is us: each definition states what the role owes and what evidence it produces, which is what makes a dispute answerable.

The rule these definitions follow

Every role is defined by what it does, never by who does it. A role defined as “whatever APIs.io does” cannot be explained to a provider who disputes their rating — and explaining is exactly what a product has to do at that moment.

1. Provider

Does: publishes APIs and decides who may call them.

Owes: a machine-readable statement of what it requires of a consumer; an evaluation of a consumer’s facts against its own policy — the provider decides, not the Directory; and honouring revocation it is told about.

Produces: an API, an access decision, and a statement of what it required.

Today: apis.io and apievangelist.com are Providers. So are the ~27,000 companies in the catalog, almost none of whom are enrolled in anything.

2. Consumer

Does: calls APIs. May be an agent, a script, or a company’s integration.

Owes: a record describing itself (KYA); attestations presented when a Provider asks; and an accurate disclosure of what it is and who it acts for.

Produces: a KYA record, a set of attestations, and API calls.

“Agent” is a special case of Consumer, not a separate role. A consumer that is autonomous raises the stakes on identity and on the Principal link below; it does not change the obligations. If autonomy turns out to change the obligations rather than only the stakes, that decision needs revisiting — it is an open question, not a settled one.

3. Principal — the party most easily forgotten

Does: nothing. Is the party the Consumer acts for.

A human whose data is being used, or an organisation whose authority is being exercised. The Consumer is not the Principal, and conflating them is how this becomes a privacy incident rather than a trust network.

Why it is the data-protection linchpin: when an agent acts for a human, two data subjects are in play — the agent’s operator and the end user — with independent rights. The consent chain runs

Principal  →  Consumer (operator)  →  Provider

and each hop needs its own basis. Open Banking solved this with explicit user consent held at the bank plus a consent dashboard; that pattern transfers directly.

Produces: consent, and the right to withdraw it.

Open: whether a Principal can address the Directory at all, or only ever a Provider. Open Banking says the latter — the end user has no relationship with OBIE.

4. Directory

Does: holds the register, publishes facts about participants, states the rules, and revokes.

Owes: a register with a stated basis for every entry and every removal; facts a Provider can check rather than take on trust; and its own enrolment recorded on the same terms as everyone else’s.

Produces: a register, graded facts, and revocations with reasons.

Today: apis.io is the Directory and a Provider. That conflict is real, is accepted rather than resolved, and is disclosed in full — including the constraints we traded away to make it a product.

What a framework version of this role would have owed, and does not: attestations verifiable without trusting the operator, signed by a separate key at a separate issuer; versioned scheme rules a third party could hold us to. Both were dropped. The replacement is reproducibility — the rubric is public and every score recomputable — which is a narrower promise and one we can keep.

5. Attestation Source

Does: verifies one fact. Is usually not us, and usually not a party to the scheme.

DNS for domain control, a CA for certificate possession, a payment rail for a funded account, an OAuth IdP for an authenticated identity, an agent provider vouching for a signed request.

Owes: verification of the one fact it is authoritative for, and nothing else. An Attestation Source does not know this framework exists.

Produces: a verifiable fact, in its own format, on its own terms.

Why it stays a named role even though we source many of our own facts. The distinction between “DNS told us” and “we computed it” is exactly what a provider disputing a rating is asking about. An assertion and an attestation are different claims; a product may make both, and must never label one as the other. That is why every fact in a KYA record carries how it was established, not just what it says.

6. Authorization Server

Does: issues tokens. May or may not be the Provider.

Auth0, Okta and Entra are common, and RFC 8414 already makes the separation machine-readable — a resource points at its authorization server, and they are frequently different parties.

Owes: published discovery metadata, tokens bound to the audience they are for, and support for whatever grant a Consumer can complete without a human where the Provider allows it.

Produces: tokens, and metadata describing how to get one.

Why it is separate: the framework must not assume a Provider issues its own tokens. Over 1,600 providers in the catalog publish authorization-server metadata; treating that as the Provider’s own surface would misattribute a third party’s infrastructure.

7. Supervisor

Does: nothing. The slot is deliberately empty.

In Open Banking this is the FCA. Here there is no regulator, no authority over the Directory, and no appeal beyond it.

The slot is named rather than omitted so that the absence is a stated fact rather than an implication. A framework that quietly has no supervisor reads as one that does not need a supervisor, and those are different claims.

What would fill it: nothing available today. A second directory verifying against the same rules is the nearest practical substitute, and it is a check rather than a supervisor — and it is not being built toward.

Does the Directory attest facts it sources itself?

Yes, and that is worth stating because the role separation above implies it should not.

The Kin Score is ours, computed by us. A Directory attesting its own computed facts is both Attestation Source and Directory for that fact. As a product this is the normal shape — it is what a rating product is. The constraint that replaces role separation is reproducibility: the rubric is published, every band cut is public, and a provider who disputes a score can recompute it before appealing.

That is a better answer to “where did you get that” than an architecture diagram, and unlike an architecture diagram it is already true.

Part of the trust layer. The two-hats conflict is disclosed separately.