Appearance
Platform API
Everything the dashboard does goes through the platform API, so your scripts, CI and billing system can do it too. Every operation is listed in the API reference, and the OpenAPI document is at /docs/openapi.json for code generators.
Base URL and authentication
text
https://microauth.com/api/v1Scripts authenticate with a workspace API key:
bash
curl https://microauth.com/api/v1/workspaces/$WORKSPACE_ID/services \
-H "Authorization: Bearer mak_..."The key's role decides what it can do, the same way it does for people. A few operations, such as creating keys, connecting Stripe and changing your MicroAuth plan, always need someone signed in to the dashboard. The reference marks them as needing a dashboard session.
The SDK API is separate: it lives on api.microauth.com and uses the SDK secret key instead.
Finding IDs
| ID | Where to find it |
|---|---|
| Workspace ID | The Workspace page, above the list of workspace API keys |
| Service ID | Settings, General, or GET /workspaces/{wid}/services |
| Customer ID | The customer's page address in the dashboard, the CSV export, or GET /services/{id}/customers?q=<email> |
Requests and errors
Requests and responses are JSON. Money is in micro-USD, and times are RFC 3339 in UTC.
Errors use application/problem+json:
json
{
"status": 422,
"title": "Unprocessable Entity",
"detail": "validation failed",
"errors": [
{ "location": "body", "message": "expected required property note to be present", "value": { "amount_micro": 25000000 } }
]
}| Status | Meaning |
|---|---|
400, 422 | The request is malformed or a field is invalid. errors says which |
401 | The key is missing, revoked or wrong |
403 | The key's role isn't enough for this operation. A viewer key gets it for any change before the body is checked, so it never sees 422 |
404 | Not found, or not in this workspace |
409 | Conflicts with the current state, like an address that's taken |
429 | Too many requests. Each client network can send 20 a second, and a workspace's keys can make 10,000 changes an hour between them. Retry-After gives the seconds until that limit lets you through, and detail ends with the same wait in words, such as Try again in 12 minutes. |
Pagination
Lists take limit, from 1 to 200 with a default of 50. When there is more, the response carries a cursor: pass next_cursor back as cursor for customers and ledgers, and next_before back as before for the activity log. An empty cursor means you reached the end.
bash
curl "https://microauth.com/api/v1/services/$SERVICE_ID/customers?limit=200&cursor=$NEXT" \
-H "Authorization: Bearer mak_..."Credit from your own billing
When you bill customers yourself, add credit once an invoice is paid:
bash
curl -X POST "https://microauth.com/api/v1/services/$SERVICE_ID/customers/$CUSTOMER_ID/credits" \
-H "Authorization: Bearer mak_..." \
-H "Content-Type: application/json" \
-d '{"amount_micro": 25000000, "note": "Invoice INV-1042", "ref": "INV-1042"}'json
{ "applied": true, "balance_micro": 37500000 }amount_microadds credit when positive and removes it when negative.25000000is $25.noteis required and shows in the customer's balance history.refmakes the call idempotent. A second call with the samerefchanges nothing and returns"applied": falsewith the current balance, so a retried job can't add credit twice. Use your invoice or payment ID.- Removing credit can take a balance below zero. The customer then gets
402until they top up.
The SDK picks up the new balance on its next snapshot, within 30 seconds.
Sign in services
Sign in services use the same base URL, keys and errors. Their operations, under /services/{id}, cover what the dashboard does: applications, APIs and MCP servers, permissions and roles, external sign in, apps people connect, API keys and users. The API reference lists every operation.
| Task | Call |
|---|---|
| Find a user | GET /services/{id}/users?q=ada@example.com. q matches part of an email or name, and status filters the list |
| Give or take a role | PUT or DELETE /services/{id}/users/{user}/roles/{role} |
| Suspend or unsuspend | POST /services/{id}/users/{user}/suspend or /unsuspend |
| Sign someone out everywhere | POST /services/{id}/users/{user}/sign-out |
| Send a password reset | POST /services/{id}/users/{user}/password-reset, which answers 202 |
| Reset two step verification | POST /services/{id}/users/{user}/two-step/reset. Needs the admin role |
| Delete a user | DELETE /services/{id}/users/{user}. Needs the admin role |
| Invite someone | POST /services/{id}/users/invites |
| List, resend or cancel invites | GET /services/{id}/users/invites, POST /services/{id}/users/invites/{invite}/resend, DELETE /services/{id}/users/invites/{invite} |
| Manage external sign in | GET and POST /services/{id}/connections, then PATCH, DELETE, /enable or /disable on /services/{id}/connections/{connection} |
| List apps people connect | GET /services/{id}/connected-apps |
| Block or unblock an app | POST /services/{id}/connected-apps/{app}/block or /unblock |
| List grants | GET /services/{id}/grants, with app or user to narrow it |
| Disconnect an app from one person | DELETE /services/{id}/grants/{grant} |
| Read or change API key settings | GET or PATCH /services/{id}/api-key-settings |
| List or add APIs and MCP servers | GET or POST /services/{id}/resources |
| Read, change or delete one API or MCP server | GET, PATCH or DELETE /services/{id}/resources/{resource}. GET answers with the same object the list has |
| Create a server's credentials | POST /services/{id}/resources/{resource}/credentials, which answers 201 with the secret once |
| Rotate a server's secret | POST /services/{id}/resources/{resource}/credentials/rotate. The old secret works for 24 hours |
| List a person's API keys | GET /services/{id}/users/{user}/api-keys |
| Revoke a person's API keys | DELETE /services/{id}/users/{user}/api-keys/{key} for one, or DELETE /services/{id}/users/{user}/api-keys for all. Both answer 200 with {"ok": true} |
| Check an MCP server | POST /services/{id}/resources/{resource}/check, up to 30 times an hour per service |
These manage your service. To sign people in or check their tokens, use the OAuth endpoints on your sign in address instead. See the OAuth and OpenID Connect reference.
Common tasks
These are for APIs you sell or run for your own teams.
| Task | Call |
|---|---|
| List your services | GET /workspaces/{wid}/services |
| Find a customer by email | GET /services/{id}/customers?q=dev@example.com |
| Suspend or reactivate | PATCH /services/{id}/customers/{customer} with {"status": "suspended"} or "active" |
| Put a customer on a plan | PATCH /services/{id}/customers/{customer} with {"plan_id": "..."}, or "" to remove it |
| Set custom limits | PUT /services/{id}/customers/{customer}/limits with rps, monthly_quota and price_per_request_micro, null to inherit |
| Invite a customer | POST /services/{id}/customers/invite with {"email": "..."} |
| List, resend or cancel invites | GET /services/{id}/customers/invites, POST /services/{id}/customers/invites/{invite}/resend, DELETE /services/{id}/customers/invites/{invite} |
| Read a customer's ledger | GET /services/{id}/customers/{customer}/ledger |
| Export customers | GET /services/{id}/customers/export |
| Read the activity log | GET /workspaces/{wid}/audit |