Skip to content

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/v1

Scripts 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 ​

IDWhere to find it
Workspace IDThe Workspace page, above the list of workspace API keys
Service IDSettings, General, or GET /workspaces/{wid}/services
Customer IDThe 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 } }
  ]
}
StatusMeaning
400, 422The request is malformed or a field is invalid. errors says which
401The key is missing, revoked or wrong
403The 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
404Not found, or not in this workspace
409Conflicts with the current state, like an address that's taken
429Too 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_micro adds credit when positive and removes it when negative. 25000000 is $25.
  • note is required and shows in the customer's balance history.
  • ref makes the call idempotent. A second call with the same ref changes nothing and returns "applied": false with 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 402 until 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.

TaskCall
Find a userGET /services/{id}/users?q=ada@example.com. q matches part of an email or name, and status filters the list
Give or take a rolePUT or DELETE /services/{id}/users/{user}/roles/{role}
Suspend or unsuspendPOST /services/{id}/users/{user}/suspend or /unsuspend
Sign someone out everywherePOST /services/{id}/users/{user}/sign-out
Send a password resetPOST /services/{id}/users/{user}/password-reset, which answers 202
Reset two step verificationPOST /services/{id}/users/{user}/two-step/reset. Needs the admin role
Delete a userDELETE /services/{id}/users/{user}. Needs the admin role
Invite someonePOST /services/{id}/users/invites
List, resend or cancel invitesGET /services/{id}/users/invites, POST /services/{id}/users/invites/{invite}/resend, DELETE /services/{id}/users/invites/{invite}
Manage external sign inGET and POST /services/{id}/connections, then PATCH, DELETE, /enable or /disable on /services/{id}/connections/{connection}
List apps people connectGET /services/{id}/connected-apps
Block or unblock an appPOST /services/{id}/connected-apps/{app}/block or /unblock
List grantsGET /services/{id}/grants, with app or user to narrow it
Disconnect an app from one personDELETE /services/{id}/grants/{grant}
Read or change API key settingsGET or PATCH /services/{id}/api-key-settings
List or add APIs and MCP serversGET or POST /services/{id}/resources
Read, change or delete one API or MCP serverGET, PATCH or DELETE /services/{id}/resources/{resource}. GET answers with the same object the list has
Create a server's credentialsPOST /services/{id}/resources/{resource}/credentials, which answers 201 with the secret once
Rotate a server's secretPOST /services/{id}/resources/{resource}/credentials/rotate. The old secret works for 24 hours
List a person's API keysGET /services/{id}/users/{user}/api-keys
Revoke a person's API keysDELETE /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 serverPOST /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.

TaskCall
List your servicesGET /workspaces/{wid}/services
Find a customer by emailGET /services/{id}/customers?q=dev@example.com
Suspend or reactivatePATCH /services/{id}/customers/{customer} with {"status": "suspended"} or "active"
Put a customer on a planPATCH /services/{id}/customers/{customer} with {"plan_id": "..."}, or "" to remove it
Set custom limitsPUT /services/{id}/customers/{customer}/limits with rps, monthly_quota and price_per_request_micro, null to inherit
Invite a customerPOST /services/{id}/customers/invite with {"email": "..."}
List, resend or cancel invitesGET /services/{id}/customers/invites, POST /services/{id}/customers/invites/{invite}/resend, DELETE /services/{id}/customers/invites/{invite}
Read a customer's ledgerGET /services/{id}/customers/{customer}/ledger
Export customersGET /services/{id}/customers/export
Read the activity logGET /workspaces/{wid}/audit

MicroAuth is a product of Zyref, LLC.