HTTP API
The HTTP API covers accounts, sessions, public keys, access grants, and operational statistics. Send account requests over HTTPS with Content-Type: application/json and Content-Length; /auth/ bodies are limited to 16 KiB, and account responses use Cache-Control: no-store. The Erlang agent has dedicated routes and limits, listed separately below.
Send a session as Authorization: Bearer TOKEN. The public routes below do not take a session. Do not retry a login, a reset, a key update, or any other call that consumes an authenticator code. A used code cannot be reused until the next time step.
API reference pages
- Authentication: enrollment, login, sessions, passwords, and authenticators.
- Account: public keys, active sessions, and account history.
- Administration: create, disable, recover, and remove accounts.
- Grants: permissions, roles, routing tokens, and sample messages.
- Statistics: chart catalog, time ranges, filters, and coverage.
Status codes
| Status | What it means for your program |
|---|---|
200 | Success. Signup is the exception and returns 201 |
400 | The JSON or a field was rejected (bad_request) |
401 | The credential was missing or rejected (unauthorized) |
403 | The caller is signed in and is not an administrator (unauthorized from the admin handlers) |
404 | Unknown route, user, or resource (not_found) |
405 | Method not allowed |
409 | The username is taken (user_exists on signup, exists on admin creates) |
429 | The account is locked, or the node rate limit fired (too_many_attempts, or history_busy on statistics) |
503 | The account service or a history query is unavailable |
Error bodies are {"error":"..."}. They do not echo passwords, codes, or tokens.
Authentication
How a person moves from signup to a session is in Enrollment. The calls are in Authentication.
| Method and path | Session |
|---|---|
POST /auth/signup | No |
POST /auth/signup/confirm | No |
POST /auth/login | No |
POST /auth/logout | Yes, empty body |
POST /auth/refresh | Yes, empty body |
POST /auth/password/reset | No |
POST /auth/password/change | Yes |
POST /auth/otp/rotate | Yes |
POST /auth/otp/confirm | Yes |
POST /auth/recovery/enroll | No |
Account
Use these after you have a session, except the public key lookup, which other programs use to encrypt to an active user. Details are in Account.
| Method and path | Session |
|---|---|
GET /auth/keys | Yes |
PUT /auth/keys | Yes |
GET /auth/sessions | Yes |
DELETE /auth/sessions/ID | Yes, body {"otp":"123456"} |
GET /auth/history | Yes |
GET /user/<name>/keys | No. Public keys for an active account |
OAuth
The browser and native flows are in OAuth.
| Method and path | Session |
|---|---|
GET /auth/oauth/providers | No |
GET or POST /auth/oauth/PROVIDER/start | No |
GET /auth/oauth/PROVIDER/callback | Browser cookies |
GET /auth/oauth/pending | Browser cookies |
POST /auth/oauth/complete | No. Body carries oauth_token and otp |
POST /auth/oauth/register | No |
GET or POST /auth/oauth/PROVIDER/challenge | No |
POST /auth/oauth/PROVIDER/token | Cookies from the challenge |
POST /auth/oauth/PROVIDER/link | Yes |
GET /auth/oauth/accounts | Yes |
DELETE /auth/oauth/accounts/PROVIDER | Yes, plus OTP |
Administration
You need an administrator session for all of these. What each action does is in Administration.
| Method and path |
|---|
GET /auth/admin/me |
GET /auth/admin/users?after=USERNAME |
GET /auth/admin/audit |
POST /auth/admin/create |
POST /auth/admin/disable |
POST /auth/admin/enable |
POST /auth/admin/revoke |
POST /auth/admin/unlock |
POST /auth/admin/recover |
POST /auth/admin/remove |
Grants, samples, statistics
| Method and path | Page |
|---|---|
GET /auth/admin/grants | Grants |
POST /auth/admin/permission | Grants |
POST /auth/admin/permission/delete | Grants |
POST /auth/admin/role | Grants |
POST /auth/admin/role/delete | Grants |
POST /auth/admin/assign | Grants |
POST /auth/admin/issue | Grants |
POST /auth/admin/grant/batch | Grants |
GET /auth/admin/samples | Grants |
GET /auth/admin/samples/ID | Grants |
POST /auth/admin/samples/examine | Grants |
POST /auth/admin/samples/pattern | Grants |
POST /auth/admin/samples/suggest | Grants |
GET /auth/admin/statistics/charts | Statistics |
GET /auth/admin/statistics/charts/CHART?from=&to= | Statistics |
Erlang agent
These routes ask the agent application to check, run, or bind Erlang. They are not account routes. Shapes, limits, and status codes are in Erlang agent.
| Method and path | Credential |
|---|---|
POST /agents/erlang | Login session, or a grant token that covers the path |
POST /agents/erlang/bindings | Grant token |
POST /agents/erlang/stdin | A credential mesgd accepts for that path |
POST /agents/erlang/stdout | Same |
POST /agents/erlang/stderr | Same |
GET /agent-ui and GET /agent-ui/... | No session. Served only when agent_ui_enabled is true |
GET and POST /auth/agent-state/... | Login session. Same config flag. Handled before other /auth/ routes |
Browser UI
GET /account and GET /account/app.js serve the account UI. A path that leaves that directory is 404.