Appearance
How selling an API works
This page covers API services, the ones you sell or run for your own teams. For sign in services, read How user authentication works.
An API service 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, unless you turn billing off. It never proxies your traffic. Your API talks to MicroAuth on the side, through the SDK or a few HTTP calls.
text
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 services, 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, its own customers and prices, and its own MicroAuth plan. A workspace can hold up to 20 services, counting APIs and sign in services together.
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 when your plan includes customer teams, 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 under Settings, Code samples.
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:
- Custom limits set on that customer's page
- The customer's monthly plan, if they have one
- Your API's default limits on the Billing 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:
json
{
"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. With billing off, the price is always 0 and billing_model is none, whatever a plan or custom limits say. Their requests a second and requests a month still apply.
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 Billing 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:
- Snapshot. About every 30 seconds, load the API's customers, key hashes and effective limits from
GET /sdk/v1/snapshotand keep them in memory. When nothing changed, MicroAuth answers with an empty304. - 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.
- Report. After the response, count it and send the counts to
POST /sdk/v1/usagein 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 and an answer to a sign up that waits for approval, whether it's approved, declined or expires. They hear about their cards, payments, refunds and disputes, a balance that runs low or runs out, changes your team makes to their account, credit, plan, limits or keys, and changes to their own team. Billing emails go to the team's admins and billing members. See emails to your customers.
- Your workspace owners and admins get new sign ups and sign ups that wait for approval, a full portal, plan allowance warnings at 80% and 100%, disputes and refunds, deleted portal accounts, team changes, Stripe account problems, domain problems and MicroAuth payment problems. Payments from your customers are available too, off by default. See your emails.
- People who sign in to your sign in service hear from it, under its name, when your team suspends or restores their account, signs them out, revokes their API keys or disconnects an app, and when they let an app use their account. See what you can do.
Dashboard and API portal accounts get an email when someone signs in from a browser the account hasn't used before. Everyone, sign in service users included, gets one when a recovery code is used, when their other sessions are signed out and when their account data is downloaded.
Sign in codes, invites, security notices, changes to someone's access and payment problems always go out. Everyone can turn the other emails off, one topic at a time, under Notifications on their Account page or with the Unsubscribe link in the email. MicroAuth's payment confirmations don't replace Stripe's own receipts or invoices, which you control in Stripe.
Emails go through a durable queue, so a mail outage delays them instead of losing them.