Quickstart
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.
1. Run the contract mock
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.
2. Ask what is available
curl -sS http://127.0.0.1:4331/developer/v1/capabilities
Every capability is listed with true or false; build only on the ones that are true.
3. Create a sandbox app
In the sandbox console (a full account is required), create a sandbox app and keep its client secret on your server, never in a browser or mobile app.
4. Get your first token
curl -sS -X POST 'http://127.0.0.1:4331/developer/v1/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode "client_id=$CLIENT_ID" \
--data-urlencode "client_secret=$CLIENT_SECRET" \
--data-urlencode 'scope=city.public.read'
5. Follow the playground
The playground has a copy-ready request for every operation and the shape of its answer. The same requests work against the sandbox with a sandbox app's credentials and the sandbox base URL from the reference.
Next
- Authentication: client credentials and user authorisation with PKCE.
- Errors: the stable problem codes every refusal uses.
- SDKs: the TypeScript SDK (source-only today).