Copy page

Operations

Onboarding

Onboarding

Onboarding is the gap between finding an API and calling it — the account, the form, the key, the consent screen. This page is every way into the APIs.io API, what each one earns, and what each one costs you.

There are four, and two of them have no human in them at all.

door	who it is for	what it costs	what it earns
Keyless	anyone, including any agent	nothing	immediate read access, limited per IP
Sign in	a person with a browser	a GitHub, Google or LinkedIn account	a Learn key, and the ability to pay for more
Sign a request	an agent with its own key	an agent provider must vouch for you	read access attributed to your identifier
Client credentials	an agent that wants its own account	the same, plus one POST	an account, an API key, its own quota

Quotas and rate limits for each tier are on the rate limits page, and what each tier unlocks is on plans. Those numbers are deliberately not repeated here — a limit written down in two places eventually disagrees with itself.

The best signup is no signup

The base tier is keyless. No account, no form, no email, no verification link:

Code
curl "https://apis.io/api/v1/search?q=sms"

Version 1 is read-only and the catalog is public, so there is no read path that requires an identity and no reason to make a machine prove one. See authentication.

Keyless callers are limited per IP rather than by a usage plan — a plan meters per key, and every anonymous caller would share one. Identifying yourself is what gets you a meter of your own, before it gets you any extra volume. See rate limits.

A person signing in

A Learn key is free with a GitHub, Google or LinkedIn sign-in, and Understanding and Influence are self-serve from your account page. Which providers are configured is itself readable:

Code
curl "https://apis.io/api/v1/auth/providers"

This is a browser flow with a person in it. We say so rather than dressing it up — if you are building an unattended client, the two sections below are the ones you want.

An agent identifying itself

APIs.io is an AAuth resource (draft-hardt-oauth-aauth-protocol). An agent holding its own Ed25519 keypair can be recognised by a service it has never registered with. There is no registration call, and no human.

Two proofs travel with the request, and both are required:

1. an aa-agent+jwt in the Signature-Key header, in which an agent provider vouches for your portable aauth:local@domain identifier and names the key it is bound to in cnf.jwk;
2. an RFC 9421 HTTP message signature over the request itself, made with that key.

The first alone is a replayable bearer token. The second alone is a self-asserted identity.

Code
Signature-Key:   sig=jwt; jwt="<aa-agent+jwt>"
Signature-Input: sig1=("@method" "@path" "@authority" "signature-key");created=…;alg="Ed25519"
Signature:       sig1=:<base64>:

The signature must cover at least @method, @path, @authority and signature-key, and carry a created parameter — without one a captured signature is valid forever. GET and HEAD need nothing more. Any other method must also sign a content-digest, because the component that verifies your signature never sees the request body and will not assert integrity it did not measure.

What signing earns is attribution: the request is recognised and audited as your identifier rather than as an anonymous address. It is not payment and it is not a paid tier.

Be precise about what it does not yet earn. Signing alone gives you no meter of your own — until you take a principal (next section) you are still limited per IP like any anonymous caller. The identifier is what makes the metering possible; the principal is what turns it on.

Our resource metadata is at /.well-known/aauth-resource.json.

The allowlist is small and you should know that before you build. The authorizer will fetch an agent provider's keys only from origins we have allowlisted, and today that list contains one entry, which is our own. AAuth is an Internet-Draft with very little deployed base; if you run an agent provider and want to interoperate, get in touch.

An agent with its own account

That same signature, presented at the token endpoint, gets an agent its own account:

Code
curl -X POST "https://apis.io/api/v1/auth/token" \
  -H "content-type: application/x-www-form-urlencoded" \
  -H "signature-key: sig=jwt; jwt=<aa-agent+jwt>" \
  -H "signature-input: sig1=(\"@method\" \"@path\" \"@authority\" \"signature-key\" \"content-digest\");created=…;alg=\"Ed25519\"" \
  -H "signature: sig1=:<base64>:" \
  -H "content-digest: sha-256=:<base64 of the body>:" \
  -d "grant_type=client_credentials"

You get back an access token, and behind it an agent principal — its own row, its own API key, its own quota, distinct from any human account in every table. No person is involved at any step.

Three things about that grant are deliberate:

• It is not anonymous, and never will be. client_credentials is reachable only by a caller already carrying a verified AAuth identity. An account that costs nothing to mint makes any reputation attached to it worthless — abuse the quota, take a fresh identity, repeat — so the price of one is that an agent provider we allowlist has to vouch for you.

• The scope ceiling is apis:read. Ask for apis:pro or offline_access and you get neither; the token's own scope says what was granted. An agent cannot self-grant paid data, and a refresh token with no user behind it is just a longer-lived credential with nobody accountable for it.

• It is reversible in one request. An agent principal can delete itself, authorised by the same signature rather than by a session cookie:

  Code
  curl -X DELETE "https://apis.io/api/v1/auth/me" \
    -H "signature-key: …" -H "signature-input: …" -H "signature: …" \
    -H "content-digest: sha-256=:<base64 of the empty string>:"

  That removes the principal, its key and its usage-plan key. Onboarding you cannot undo is an asymmetry we penalise other providers for, so we do not ship it here.

GET /api/v1/auth/me with the same signature reports what the principal currently is.

Read the door before you knock

Everything above is declared in one machine-readable document, so a client does not have to read this page to know any of it:

Code
curl "https://apis.io/.well-known/api-onboarding"

That is an API Onboarding Descriptor — whether an account is required at all, an explicit agentPolicy, every registration mechanism that exists and precisely what each is worth, how credentials map to header names, an executable flow, and a gaps array saying what does not work yet. Where this page and that document disagree, the document is the one we test.

The OAuth surface is discoverable the same way:

document	what it tells you
/.well-known/oauth-authorization-server	RFC 8414 metadata — endpoints, grants, scopes, and a registration_endpoint
/.well-known/oauth-protected-resource	RFC 9728 — which authorization server protects this resource
/.well-known/aauth-resource.json	the AAuth resource document

Clients can register with no human through RFC 7591 dynamic client registration or a Client ID Metadata Document (a client_id that is a URL resolving to its own metadata). Both are supported; both are for the MCP surface and the OAuth flows, and neither by itself yields an account or a paid tier.

What you still cannot do without a person

Stated plainly, because a page like this is where providers usually stop being honest:

• You cannot buy anything. Every path above tops out at free. Understanding and Influence need a card, a browser and a human, and machine payment is not solved here. An above-tier request returns 402 Payment Required — a payment signal, distinct from a permission failure and distinct from being throttled.
• AAuth is a draft with almost no deployed base, and one agent provider on our allowlist. Treat it as a working implementation to test against, not as an ecosystem.

The last human-shaped step in getting started here is the one where money changes hands. We think that is a more interesting place for it to be than a signup form — but it is still there.