Developer docs

Short guides for the sandbox Developer API. The API reference lists every operation and is generated from the same contract file you can download, so the two cannot disagree.

Your first call

Run the contract mock locally: pnpm --filter @ao/developer-gateway mock. It serves http://127.0.0.1:4331/developer/v1 from the contract, with no credentials and no player data.
Ask what is available: GET /developer/v1/capabilities. Every capability is listed with true or false; build only on the ones that are true.
Create a sandbox app in the sandbox console (a full account is required) and keep its client secret on your server.
Follow the playground: each operation with a copy-ready request and the shape of its answer.

Tokens

App tokens come from POST /oauth/token with grant_type=client_credentials, your client_id and client_secret, form-encoded. They last 300 seconds and only carry the scopes your app was granted. Never put the client secret in a browser or a mobile app.

User tokens need a player's consent on africaone.io: authorization code with PKCE (S256), the exact registered redirect URI and an unguessable state. Refresh tokens rotate on every use, so store the new one each time. A refused refresh means the player must authorise again. The full flow is in user authorisation.

Errors

Every refusal is application/problem+json with a stable code and a request_id to quote to support.

Code	Status	What to do
`UNAUTHENTICATED`	401	Send a valid access token.
`ACCESS_DENIED`	403	The token is for another environment or audience, has expired, or the app is not active. Get a new token for this environment.
`CONSENT_REVOKED`	403	The player withdrew access. Ask them to authorise again.
`USER_TOKEN_REQUIRED`	403	This operation needs a token a player authorised, not an app token.
`INSUFFICIENT_SCOPE`	403	Your app was not granted this capability.
`FEATURE_DISABLED`	503	The capability is switched off here (always so in production today).

Signed webhooks

Deliveries carry four headers: AfricaOne-Webhook-Id, -Timestamp, -Key-Id and -Signature (ao1= followed by hex HMAC-SHA256). To verify:

Compute HMAC-SHA256 with your endpoint secret over timestamp + "." + event_id + "." + raw_body, using the exact bytes you received.
Compare in constant time. Use the secret named by the key id (rotation overlap).
Refuse timestamps more than 300 seconds from your clock.
Only after the signature verifies, record the event id and refuse repeats for 7 days.

TypeScript SDK

A TypeScript SDK lives in the AfricaOne repository at sdk/typescript. It includes types generated from this contract, a typed client, the token and PKCE helpers and the webhook verifier, and it runs in browsers, Node, Deno and edge runtimes. It is not published as a package yet. Other languages follow after the TypeScript one.

Versions

The contract is versioned (reference shows the latest v1; every published version stays downloadable). Additive changes raise the minor version. Anything that would break a client needs a new major path, never a silent change to /developer/v1.