API Onboarding Descriptor

We standardized the API — we didn't standardize the application. OpenAPI describes what an API does. OAuth, dynamic client registration, and client ID metadata documents describe the credential handshake. Nothing describes what it takes to get there: the account, the plan tier, the terms of service, the verification queue, and the console a human still has to click through. The API Onboarding Descriptor is a machine-readable document, published at /.well-known/api-onboarding and referenced from an APIs.json index, that closes that gap — for developers and for the agents now doing the onboarding.

Spec + Schema on GitHub ↗ JSON Schema Example Descriptors
The descriptor was not designed on a whiteboard — it was derived by induction from working onboarding scripts written against 36 API providers, gateways, and identity platforms. Every provider turned out to be answering the same six questions in a different vocabulary: what a human must do first, what credential you walk away with, what gates sit in the way, what happens when the application already exists, how access is scoped, and what gets printed at the end. The descriptor writes those answers down in one shape.

self-serve — the open door

A stranger (or their agent) can authenticate through a public flow and walk away with credentials. No pre-existing token anywhere. Of 36 providers profiled, exactly one clears this bar.

bootstrap-token — the keyed door

A real management API exists and everything is scriptable — except the first token, which a human mints in a console and pastes into an environment variable. Twenty-five of 36 live here.

console-only — the human door

No complete programmatic path exists; a browser dashboard is load-bearing. The descriptor's gaps section states this honestly, so it doubles as the provider's punch list.

What a descriptor declares

Maturity level, account prerequisites and plan gates, an explicit agentPolicy, terms of service, verification queues with expected latency, the registration mechanisms that exist (open — no registration at all, browser OAuth, app manifest, management API, portal API, RFC 7591 DCR, CIMD, aauth, or console-only), credential shapes mapped from provider vocabulary to canonical fields, and the scope model.

Two mechanisms the 36-provider corpus did not contain

open came from dogfooding: some APIs need no registration at all, and a descriptor with no way to say “the door is simply open” forces a keyless provider to describe itself as if it had a gate. aauth came from implementing one — a caller signs the request with its own key (RFC 9421) and presents a token in which an agent provider vouches for its aauth:local@domain identifier, so a resource can recognise a caller it has never registered. Its authentication method type is request-signing. Both were added by induction from a working implementation, which is the only way a field gets into this spec.

The ladder needs a rung above self-serve

self-serve is defined as a stranger, or their agent, authenticating through a public flow. That conflated two things which have now come apart in practice: a stranger with a browser, and a stranger with no human anywhere in the loop. A provider where an agent signs a request, exchanges it for its own principal and deletes that principal again — no person at any step — is not the same door as one where somebody clicks a consent screen, and the current enum cannot tell them apart. Deliberately unresolved here rather than quietly patched: whether that is a fourth rung or a second axis is a spec decision, not an editorial one.

An executable flow

The part that keeps the spec honest: ordered HTTP steps with environment and argument templating, per-status recovery (a 409 routes to a read-back instead of failing), and output mappings. A generic engine — api-onboard.mjs, one file, Node stdlib, no npm install — runs the flow and prints client_id= to stdout. If the engine can't onboard from the descriptor alone, the descriptor grows a field. That loop is the spec process.

Built on existing standards

The descriptor deliberately does not reinvent the handshake. Where a provider supports RFC 7591 dynamic client registration or Client ID Metadata Documents, the descriptor points at them. It is the discovery-and-paperwork layer around OAuth and its descendants — the account, plan, ToS, and verification reality those standards assume away.

Live descriptors

We publish descriptors for our own APIs, the same way we ask every provider to:

Read the story behind the specification — What 36 Providers Taught Me About Programmatic API Onboarding — and the posts that led to it on API Evangelist. Open source and free to adopt; API Evangelist offers expert services when you want help profiling and fixing your own onboarding.