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).

At enforcement time these resolve into one set of effective limits, in priority order:

1. Custom per-customer overrides (highest priority)
2. The customer's subscription plan
3. 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.

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 and only count/report responses whose status matches. 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:

1. Snapshot — periodically fetch all customers, keys and effective limits for the tenant (GET /sdk/v1/snapshot) and cache them in memory or Redis.
2. Enforce locally — on each request, hash the presented key, look it up in the cache, and enforce suspension, balance, quota and RPS with no network call.
3. Report — count billable responses per key, and flush the counters to MicroAuth in batches (POST /sdk/v1/usage). MicroAuth charges the customer's balance server-side.

This keeps your latency flat, keeps your API up even if MicroAuth is briefly unreachable, and — because usage is bucketed per hour and applied server-side — stays correct across many workers and machines.

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.