How MicroAuth works

MicroAuth gives your API three things: a developer portal for your customers, key checks and limits that run inside your own service, and billing for what each customer uses. It never proxies your traffic. Your API talks to MicroAuth on the side, through the SDK or a few HTTP calls.

 your customer             your API with the SDK              MicroAuth
+--------------+  request  +------------------------+ snapshot +-----------+
| X-API-Key:   |---------->| check key, limits and  |<---------| customers |
| map_...      |<----------| balance in memory      |  usage   | keys      |
+--------------+ response  | serve, then count it   |--------->| billing   |
                           +------------------------+          +-----------+

Workspaces and APIs

A workspace is your account in the dashboard. It holds your APIs, the people on your team and your workspace API keys. You can create more workspaces to keep clients or side projects apart.

An API is one product you sell. It has its own name and branding, its own portal at https://<slug>.microauth.dev (or your own domain), its own customers and prices, and its own MicroAuth plan. A workspace can hold up to 20 APIs.

Each API has an SDK secret key (mas_...). Your server sends it to MicroAuth to load customers and report usage. Anyone who can edit the API can reveal it on the Connect tab, and admins can rotate it under Settings.

Customers

Developers who sign up on your portal are your customers. A customer is always a team. A solo developer is a team of one, and on the Scale plan a team can invite colleagues with these portal roles:

Role	Can do
Admin	Everything, including inviting and removing teammates
Developer	Create and revoke API keys, see usage
Billing	Add credit, change plans, manage cards and invoices

The balance, plan, limits and usage all belong to the team. Every customer ID you see, in the dashboard or as customers[].id in the snapshot, is a team ID.

Each API also has one test customer. Its key is on the Connect tab, it pays with test credit, and it isn't counted against your plan's customer limit. Use it to try your integration without signing up.

Keys at a glance

MicroAuth uses three kinds of key, told apart by their prefix. MicroAuth only stores a SHA-256 hash of customer and workspace keys.

Prefix	Name	Used for	Sent to
mas_	SDK secret key	Loading customers and reporting usage	api.microauth.com, from your server
mak_	Workspace API key	Automation through the platform API	microauth.com/api/v1, from your scripts
map_	Customer API key	Calling your API	Your API, from your customers

Customers create their own keys on the portal, up to 20 per team, and send them in the X-API-Key header unless you choose another header name on the Portal tab.

Money is in micro-USD

Every amount in the API is a whole number of micro-USD: 1,000,000 is one dollar, so a price of 1000 per request is $0.001. Whole numbers keep every charge exact. The dashboard and portal show normal dollar amounts.

Customers hold a prepaid balance. Billable requests are deducted from it at the customer's price. Credit arrives through a welcome credit, Stripe top ups, monthly plan credit, a grant from the dashboard or your own billing system through the credits endpoint. Every change is recorded in the customer's ledger.

Effective limits

Three layers decide what one customer gets. A higher layer wins, field by field:

1. Custom limits set on that customer's page
2. The customer's monthly plan, if they have one
3. Your API's default limits on the Pricing tab

A field left blank inherits from the layer below. For requests a second and requests a month, 0 means no limit. The result is what the SDK enforces:

{
  "rps": 10,
  "price_per_request_micro": 1000,
  "monthly_quota": 100000,
  "source": "plan",
  "billing_model": "subscription"
}

monthly_quota is left out when there is no quota. source says which layer won: custom, plan or payg. billing_model is subscription for customers on a plan, payg when requests cost money and none when they are free. When pay as you go is off, customers without a plan don't pay per request and only get the default limits.

Billable status codes

Not every response should cost money. Each API has a list of billable status codes, 200 to 206 by default, on the Pricing tab. The SDK reports every authenticated response so quotas and your plan's allowance stay accurate, but only billable responses are charged. A 404 or 500 costs your customer nothing unless you add it.

Snapshot and report

The SDK, or your own code, follows one pattern:

1. Snapshot. About every 30 seconds, load the API's customers, key hashes and effective limits from GET /sdk/v1/snapshot and keep them in memory. When nothing changed, MicroAuth answers with an empty 304.
2. Check locally. For each request, hash the key, look it up in memory and apply suspension, balance, quota and rate limits with no network call.
3. Report. After the response, count it and send the counts to POST /sdk/v1/usage in batches. Each item has a stable idempotency key, so a retry is never billed twice.

Every customer in the snapshot carries a usage_policy_id. Usage reported under that policy is charged at the prices it was issued with, so changing your prices never reprices requests that were already served.

Payment problems

When a customer's subscription payment fails, they keep their plan while Stripe retries the card, and MicroAuth emails them to update it. If Stripe finally cancels the subscription, the customer drops back to your default limits. Nothing is deleted.

Your own MicroAuth plan works the same way, with a 7 day grace period before the API moves to the Free plan.

Emails

MicroAuth sends emails for the events that matter, with your API's name and colors on everything a customer receives:

• Your customers get sign up codes, invites, approval notices, low balance alerts, failed payments, failed automatic top ups and a notice when a plan ends. Billing emails go to the team's admins and billing members. Payment receipts come from Stripe.
• Your workspace owners and admins get sign ups that wait for approval, a full portal, plan allowance warnings at 80% and 100%, disputes, Stripe account problems and MicroAuth payment problems.

Emails go through a durable queue, so a mail outage delays them instead of losing them.