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 (browser OAuth, app manifest, management API, portal API, RFC 7591 DCR, CIMD, or console-only), credential shapes mapped from provider vocabulary to canonical fields, and the scope model.

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.