Core concepts
MicroAuth lets you launch an API business in minutes: a branded developer portal for your customers, plus API key authentication, rate limiting and metered billing enforced inside your own API. MicroAuth never proxies or inspects your traffic — your API talks to MicroAuth out-of-band, through an SDK or the SDK API.
The three surfaces
| Surface | URL | Who uses it |
|---|---|---|
| MicroAuth app | app.microauth.com | You and your team — manage workspaces, tenants, plans, customers |
| Developer portal | https://<subdomain>.microauth.dev or your custom domain | Your API customers — sign up, create keys, top up, subscribe |
| MicroAuth API | https://api.microauth.com | Your backend and SDKs — management API and SDK API |
Workspaces
A workspace is the top-level account container in MicroAuth. You can be a member of several workspaces, each with its own team and roles (owner, admin, member). Everything you create — tenants, workspace API keys, billing — belongs to a workspace.
Tenants
A tenant is one API business: it has a name, branding (logo, colors), a *.microauth.dev subdomain, optionally a custom domain, and its own white-labeled developer portal. If you run a weather API, proweather is a tenant; https://proweather.microauth.dev is its portal.
Each tenant has a tenant secret key (mas_...) — the credential your backend/SDK uses to talk to the SDK API. It is shown once at creation and can be rotated at any time from the tenant's overview page.
Customers (portal workspaces)
People who sign up on your developer portal are your customers. Each customer account is itself a small workspace — a team. A solo signup is simply a team with one member; larger accounts add teammates with portal roles (admin, developer, billing manager). Customers create API keys (map_...) that they send to your API — typically in an X-API-Key header.
Billing always attaches to the team, not to individual users: the credit balance, ledger, usage, quotas and plan all belong to the portal workspace, and every customer ID you see in the API (customerId, the SDK snapshot's customers[].id) is a team ID. One person can belong to several teams, each with its own balance and limits.
API keys at a glance
MicroAuth uses three key types, distinguishable by prefix. All are shown once at creation; MicroAuth stores only a SHA-256 hash.
| Prefix | Name | Used for | Sent to |
|---|---|---|---|
mas_ | Tenant secret key | SDK API: snapshots, key verification, usage reporting | api.microauth.com (from your backend) |
mak_ | Workspace API key | Management API: automation, external credits | api.microauth.com (from your billing/backoffice systems) |
map_ | Customer API key | Authenticating requests to your API | Your API (from your customers) |
Credits and micro-USD
All money amounts in MicroAuth are integers in micro-USD: 1,000,000 micro = $1.00. A price of 500 micro per request is $0.0005. Integer math avoids floating-point rounding errors in billing.
Customers hold a prepaid credit balance. Billable requests are charged against it at the customer's effective per-request price. Credits arrive via:
- Stripe — top-ups and subscription plans, if you connect your Stripe account to the tenant (fully automated, webhook-driven).
- External billing — your own system calls the credits endpoint with a workspace API key.
Every movement is recorded in a per-customer credit ledger.
Plans and effective limits
For each tenant you can offer subscription plans (a monthly credit grant plus a per-request price, RPS and quota) and/or pay-as-you-go defaults. You can also set custom overrides per customer. Plans can be public (visible to everyone on the portal) or private (visible only to assigned customers).
When plan metadata appears in an API response, plan_id is a UUID encoded as a JSON string, or null when no plan is assigned. plan_name is a JSON string, or null in the same case. Neither field is a numeric plan code.
At enforcement time these resolve into one set of effective limits, in priority order:
- Custom per-customer overrides (highest priority)
- The customer's subscription plan
- Pay-as-you-go tenant defaults
The resolved object looks like:
{
"rps": 10,
"price_per_request_micro": 500,
"monthly_quota": 1000000,
"source": "plan",
"billing_model": "subscription"
}monthly_quota may be absent (no cap). source tells you which layer won: custom, plan, or payg.
MicroAuth platform request allowance
The plan that the API owner buys from MicroAuth also has a monthly tracked request allowance. This is separate from the quota that the API owner gives one customer. The SDK snapshot publishes the authoritative platform values:
{
"platform_monthly_limit": 10000000,
"platform_monthly_used": 48210,
"platform_monthly_remaining": 9951790,
"platform_period_end": "2026-09-01T00:00:00Z",
"platform_hard_cap": true
}The API rejects a usage item that would exceed this allowance, but a report is sent after the customer request has run. For proactive enforcement, a conforming SDK reserves one request locally before it invokes the application handler and reconciles that reservation when usage is reported.
This is an honest-client safety control, not an untrusted gateway guarantee. The API owner controls the code and can bypass or modify its SDK, and concurrent processes can admit requests before reports converge. Redis can coordinate conforming processes, but it does not turn code in customer infrastructure into a hard security boundary. Put enforcement in a trusted gateway if the platform allowance must be globally strict.
Billable status codes
Not every response should cost money. In tenant settings you choose which HTTP status codes are billable (default: 200 only). SDKs receive this list in the snapshot. They report every authenticated response for request allowance and customer quota accounting, but only matching statuses charge the customer balance. A 404 or 500 never charges your customer unless you say so.
Enforcement model: snapshot + report
The MicroAuth SDK (or your custom integration) follows one pattern:
- Snapshot — periodically fetch all customers, keys and effective limits for the tenant (
GET /sdk/v1/snapshot) and cache them in memory or Redis. - Enforce locally — on each request, hash the presented key, look it up in the cache, reserve monthly usage, and enforce suspension, balance, quota and RPS with no control-plane network call.
- Report — record every authenticated response and flush it to MicroAuth in batches (
POST /sdk/v1/usage). Every item carries a stable idempotency key, the verified API key UUID, the immutable usage-policy UUID from the customer snapshot, the final HTTP status, a positive count, and an hourly UTCperiod_start. Retain the item until MicroAuth returns its item-level acknowledgement. MicroAuth counts usage and applies charges under that captured policy, so a later pricing change cannot reprice queued traffic.
This keeps normal authentication off the network path. New-key verification, shared RPS limits, and recovery from stale data can still require network or Redis access. Usage is bucketed by hour for reporting, while stable item IDs make timeout retries safe across workers and process restarts. A duplicate idempotency key with different item content is rejected rather than counted again.
Subscription payment grace
A failed Stripe subscription payment starts a 7-day grace period. Paid entitlements remain available during grace so the account can update its payment method. A successful payment clears the grace state. If the grace period expires, MicroAuth marks the affected tenant or customer billing_suspended without deleting its data. Reconciliation must repair state if a webhook is delayed or missed. See Stripe webhooks and reconciliation.
Customer email notifications
MicroAuth emails your customers about the billing events that affect their service, using your tenant branding: your logo, colors, support email, and docs link. Emails go to the workspace members whose role includes billing access, which means admins and billing managers but not developers.
Three groups of notifications can be switched on or off by each member on their portal Profile page (all are on by default):
- Balance alerts: a warning when the prepaid balance drops below the workspace's alert threshold, and a notice when credits run out and requests start returning
402. The threshold defaults to $5.00 and each workspace can raise it on the Billing page. Every alert fires once per depletion cycle; adding credits re-arms it. - Billing activity: top-up confirmations, manual credit adjustments, monthly plan credits, and credits removed after a refund or dispute.
- Subscription updates: new subscriptions, plan changes, cancellations, and payment recovery confirmations.
Two kinds of email ignore these toggles because skipping them risks real harm: security messages (verification codes, sign-in lockout alerts, and invitations) and payment problem notices (a failed subscription payment opening the grace period, and the suspension that follows if it lapses).
Delivery rides the same durable outbox as every other MicroAuth email, so a mail provider outage delays notifications rather than dropping them, and webhook retries can never send the same notice twice.
Next steps
- Getting started — from signup to your first authenticated request.
- FastAPI SDK — the two-line integration.
- Custom integration — the same pattern in any language.