API Reference
AppID exposes two distinct API surfaces — don’t mix them up:
| Surface | Base | Auth | For |
|---|---|---|---|
| Control plane | https://api.dodil.io/v1/appid | Platform bearer (dodil auth login token) | You — managing pools, users, tenants, stores |
| Issuer API | https://appid.dodil.io/{org}/{pool} | None / end-user credentials / pool tokens | Your app and its end users |
Control-plane conventions
- Org-free requests. No request carries an organization — the gateway resolves your org from the bearer and scopes every call to it.
- Envelope: responses arrive as
{ "data": …, "status": "success" }with camelCase fields. - Errors map from the underlying RPC: 400 invalid argument, 403 permission denied (missing role/scope), 404 not found, 409 conflict, 503 pool busy (migration in its locked phase).
- Authorization is scope-checked per method — the scope names and the
appid.admin/appid.viewerroles are listed in Auth and Access.
Route map
| Area | Routes | Page |
|---|---|---|
| Pools, connections, keys, user stores | POST/GET /pools, GET/PATCH/DELETE /pools/{pool}, …/connections, …/rotate-keys, …/user-store, …/user-store/migrate | Pools |
| Users & tenants | …/users, …/users/{id}/…, …/tenants, …/tenants/{tenant}/members | Users & Tenants |
| Health | GET /v1/appid/healthz | — |
Issuer API
The per-pool public surface — discovery, JWKS, authorize/token, signup, recover/reset/verify, userinfo, branding — is documented on its own page: Issuer API. It is intentionally not behind api.dodil.io; it must be reachable by browsers and by anyone verifying your tokens.
gRPC
The control plane is a gRPC service (dodil.appid.v1.AppIdService) that the gateway maps to the REST routes above; the protos live in dodilio/proto-appid. Field names below are shown in their REST (camelCase) form.