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 six, and four of them have no human in them at all. The first two are the ones an unattended agent can walk through unaided — one to be listed, one to be served paid data; every other door needs a person or a voucher.

door	who it is for	what it costs	what it earns
Register your agent	an agent that serves an A2A agent card	serving a conformant card on a host you control, then one POST	a place in the agent registry, verified against your card
Pay per call (x402)	an agent with a USDC wallet on Base	the price of the call, quoted in the refusal	that one call, at the tier it needs — no account, no key
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.

Register your agent — the door written for an agent to execute

Serve an agent card at /.well-known/agent-card.json on a host you control, then tell the registry where it is. No account, no form, nothing to wait for from us: the card is the evidence.

Code
curl -X POST https://apis.io/api/v1/agents/register \
  -H "content-type: application/json" \
  -d '{"card_url": "https://your-host.example/.well-known/agent-card.json"}'

202 queues the registration; 422 names the check that failed (the card must be fetchable and pass the three A2A 1.0.0 hard checks — capabilities is an object, protocolVersion is present, skills is an array). A bare GET on the same path returns this contract, so an agent that lands there without this page can still proceed. The registry itself is GET /api/v1/agents, free; the MCP tools are find_agents and register_agent; the human-readable procedure is at apis.io/agents/register.

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, apis:business or offline_access and you get none of them; 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.

Pay per call — the door with no account behind it

A paid resource you call without the plan for it answers 401 (no credential) or 402 (a key below the tier). Where the call is sold per call, both carry an x402 payment requirement: an accepts array in the body (x402 v1) and a PAYMENT-REQUIRED header (x402 v2), priced in USDC on Base mainnet at the same number price_usd quotes. The body's resolution says "self_serve": true.

Sign one of the requirements with your wallet, send it in X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2), and retry the exact request. The payment is settled before the response is served, and the receipt comes back in X-PAYMENT-RESPONSE or PAYMENT-RESPONSE. Any stock x402 client does this for you.

Code
curl -s "https://apis.io/api/v1/ratings?limit=2" | jq '{error, price_usd, accepts, self_serve: .resolution.self_serve}'

Two things are never sold this way: bulk export, which is priced per row and cannot be quoted before it runs, and anything a person has to do. Those refusals carry no accepts block. For volume, a plan is cheaper than paying call by call.

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.

A dynamically registered client is reversible. The registration response carries a registration_access_token — shown once — and a registration_client_uri; send the token as a Bearer credential to GET, PUT or DELETE that URI (RFC 7592). A client that is never exchanged for a token is removed after seven days, so a test registration cleans itself up. Registrations are capped per hour across all callers, and the response headers say how many remain.

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 with a valid key returns 402 Payment Required — a payment signal, distinct from a permission failure and distinct from being throttled. The same request with no key returns 401, which asks you to identify yourself first; an agent that treats every 401 as a broken token will loop on a paywall it never sees.
• 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.