Skip to content

Security and privacy ​

MicroAuth is a control plane, not a proxy. People sign in on pages MicroAuth hosts, and your customers call your API directly. MicroAuth sees account data, configuration and what your integration sends it. It never sees your request bodies, headers, query parameters or responses.

What MicroAuth receives ​

From your API, through the SDK or the HTTP API:

  • SHA-256 hashes of the keys your customers send, never the keys themselves.
  • Usage items: the key ID, the status code, a count, the hour it happened, the usage policy and an idempotency key.
  • The SDK's User-Agent, so the dashboard can show which version you run.

From your apps, APIs and MCP servers on a sign in service:

  • Codes and refresh tokens at the token endpoint, and requests for signing keys. Access tokens are checked inside your servers without calling MicroAuth.
  • API keys your users create, but only when your server checks one with introspection. The key travels over TLS, is hashed on arrival and is never logged.

From people: names, email addresses, profile photos and the settings they choose, plus the sessions and connected apps of the people who sign in through your services. Card details go to Stripe and never reach MicroAuth.

Credentials ​

CredentialHow it is stored
Customer API keys (map_)SHA-256 hash and a short prefix for display. Shown once
API keys your users createSHA-256 hash and a short prefix for display. Shown once
Workspace API keys (mak_)SHA-256 hash and a short prefix. Shown once
SDK secret keys (mas_)Encrypted at rest, so editors can reveal them on the Connect tab
Application secrets and server credentialsShown once. Rotating keeps the old secret working for 24 hours
Token signing keysOne RSA key per sign in service, encrypted at rest. Only the public key is published
Client secrets for Google, GitHub and other providersEncrypted at rest
Passwordsbcrypt hashes
Two step secretsEncrypted at rest. Each code is accepted once
Recovery codesHashes. Each code works once
PasskeysThe public key and credential ID only. The private key stays on the person's device or in their password manager
StripeOnly your connected account's ID. MicroAuth never holds your Stripe keys

Rotating the SDK secret. Admins rotate it under Settings, SDK secret key, and choose how long the old one keeps working, from 0 to 168 hours, 24 by default. Deploy the new secret within that window. A leaked secret can read your customers' key hashes and limits and report usage, so rotate it with a grace of 0 if you think it was exposed.

Where checks happen ​

The SDK runs inside your API, so its checks are exactly as strong as your deployment. That is the point: there is no hop to MicroAuth on the request path. It also means MicroAuth trusts the usage your server reports. Keep the SDK secret on the server, never in a browser or mobile app.

Customers can't get around the checks without getting around your own code. Rate limits are exact per process, and exact across processes once you add Redis.

Sign in services ​

  • Every app signs people in with the authorization code flow and PKCE (S256). There is no implicit flow and no password grant.
  • Redirect URIs match exactly. A request with an unknown app or redirect URI shows an error page and never redirects.
  • Every authorization response names the issuer (RFC 9207), so a client can't be tricked into sending a code to the wrong service.
  • Codes last 60 seconds and work once. If a code is used twice, the refresh token from its first use stops working at once, and so do its access tokens at introspection and userinfo.
  • Access tokens name one API or MCP server in aud, and a token for one server is refused at another.
  • Refresh tokens change on every use. Reusing an old one after a 30 second grace revokes the whole chain.
  • When a signing key is rotated, the old public key stays published for the access token lifetime plus 24 hours, then goes.
  • Apps people connect get nothing until the person approves them on a consent screen, and people can disconnect them at any time. Every one of them is labeled unverified, none gets a client secret, and you can block one for everyone.
  • When MicroAuth fetches an app's metadata document or calls an external provider, it only connects to public addresses over https. It pins the address it looked up, follows no redirects and reads at most 5 KB of metadata.
  • External sign in keeps its state, nonce and PKCE verifier on MicroAuth's side. A provider account only links to an existing account on its own when the provider and the account both have the email verified.
  • The authorization, token, consent and registration endpoints are rate limited per network. The token endpoint is also limited per app, and the consent screen per person and app. Introspection with server credentials that check out is limited per set of credentials, to 100 requests a second in bursts of up to 1000. A request with a wrong secret counts against its network's limit instead.

Isolation ​

  • Everyone in the dashboard acts inside a workspace with a role, and every request is checked against it.
  • Each sign in service and each portal has its own sessions, in __Host- cookies on https, so signing in on one means nothing on another.
  • On a sign in service, codes and refresh tokens only work at the address that issued them, and each service signs tokens with its own key.
  • On a portal, keys, usage, billing and teammates belong to one customer team, and each member's role decides what they can see and change.
  • Requests that change data are checked against the site they came from, which blocks cross site request forgery.
  • All traffic uses TLS, including portals on custom domains.

Sign in protection ​

The dashboard, every portal and every sign in service limit how fast anyone can guess a code or a password:

  • Each emailed code allows only a few tries. Tries are also counted per email address over the hour and over the day, and asking for a new code doesn't reset that count.
  • One address can get 3 codes every 15 minutes and 10 a day for each kind of code, such as sign up or a password reset, so nobody can flood an inbox. After that, a request gets 429 with Retry-After and a message that says when to try again. Requests count the same way whether or not the address has an account, so the limit doesn't reveal who has signed up.
  • Checking a code answers the same way whether or not the address has an account, so the answers don't reveal who has signed up.
  • Sign in is limited per email address and per network. Two step codes, password changes and two step setup are limited per account, and two step codes also have a daily cap.
  • Sign up is limited per email address and per network. Each portal and sign in service counts a network on its own, with a higher cap across all of them, so one busy office can't block sign ups everywhere.
  • Passkey sign in is limited per network. Each passkey request works once and expires after 5 minutes, and it is tied to the exact address it was made for, so a portal's passkey means nothing on another portal.
  • Limits are kept in the database, so they hold through restarts, deploys and requests sent at the same time. They refill over time, and they're stored as keyed hashes, not as email or IP addresses.
  • Every limit answers 429 with Retry-After, the seconds until that limit lets the same caller through, and a message that ends with the wait, such as "Try again in 12 minutes." The wait comes from the caller's own count, so it doesn't say anything about other people.
  • The dashboard and each portal count tries per address separately, so running out on one doesn't lock that address out of another.

Passwords for the dashboard are covered in Team and security, and passkeys and two step verification in Passkeys and two step verification. For portals, see signing in to a portal.

Unsubscribe links ​

Emails people can turn off end with an Unsubscribe link and carry the List-Unsubscribe and List-Unsubscribe-Post headers (RFC 8058), so mail apps such as Gmail can show their own one-click button. Emails that always go out, such as sign in codes, have no link.

  • Each link is signed and names one person and one topic, so it can't be edited to point at someone else. Links stay valid for 3 years.
  • Opening a link shows a page that asks first. Link scanners in mail systems only open links, so they can't unsubscribe anyone.
  • Confirming, or the mail app's own button, turns off that one topic and nothing else.
  • A portal link only works on that API's own portal.

Billing integrity ​

  • Every balance change is a ledger entry with a unique reference, so retried webhooks and repeated API calls never credit or charge twice.
  • Usage reports are idempotent, and each request is charged at the prices that applied when it was served.
  • Stripe webhooks are verified against their signature and stored before they are processed. Subscriptions and payments are read back from Stripe before they are applied, so events that arrive out of order can't roll anything back.
  • Every night, each customer's balance is checked against the sum of their ledger, and any difference is flagged to the MicroAuth team.

When MicroAuth is unreachable ​

Known keys keep working from the cached snapshot, and usage waits in the SDK's queue until MicroAuth is back. With the default settings, the SDK serves known keys from a stale snapshot for up to 15 minutes before it answers 503. New keys can't be checked until MicroAuth is reachable again. See the FastAPI SDK guide for the settings.

On a sign in service, your APIs and MCP servers keep checking access tokens with the signing keys they cached. New sign ins and token refreshes wait until MicroAuth is back. UserAuth sessions keep working for up to 5 minutes past their access token's expiry, then routes answer 503. API keys your users created keep working for up to 10 minutes past the SDK's cached answer, and keys that can't be checked get 503.

Abuse and impersonation ​

Sign in pages and portals live on MicroAuth's addresses, so MicroAuth makes sure they can't be used to trick people into giving away a password.

What's refused. A service's address and name are checked when it's created and every time they change.

  • Addresses that contain a well known brand, such as paypal-secure or googleverify. The list covers big tech, email, payments, banks, crypto, social networks, shipping companies and MicroAuth itself.
  • Addresses with a part like verify, password, wallet, recovery or bank, such as acme-verify. Sign in words are fine, so acme-login works, but not next to a brand, as in paypal-login.
  • Names that are a brand, alone or with sign in words, such as "PayPal", "Google Sign In" or "Microsoft Account". A brand word used in another sense, like "Apple Farm", is fine, and so is a name like "Supportly".
  • Lookalike letters, digits and accents count as the letters they imitate.

If a brand is yours, email hello@microauth.com. A workspace can create up to 10 services a day, and its owner has to verify their email before creating the first one.

Reporting a page. Anyone can report a page at microauth.com/report, with no account and no JavaScript. To link to the form from a page, add the page's own origin:

text
https://microauth.com/report?url=https://acme.microauth.dev

The form fills in the address only when MicroAuth serves it. Each network can send a few reports an hour, and every report is emailed to the MicroAuth team. Reports about addresses MicroAuth doesn't serve are read too.

What suspension does. When a service breaks the rules, or there's a billing problem with the account behind it, MicroAuth suspends it and emails its owner. The email and the dashboard say which it is and what to do next.

  • Every page it hosts, including /oauth/authorize, shows a plain "This page is unavailable" page with no name, logo, forms or scripts.
  • The token endpoint answers invalid_grant, userinfo answers invalid_token, introspection answers {"active": false}, and registration, pushed requests and consent answer access_denied. Revoking a token still works.
  • Discovery and JWKS answer 404. APIs that cached the keys accept access tokens they already have until those expire, 10 minutes by default, and no new ones are issued. An error is used instead of an empty key set so that nothing caches a broken document, and lifting the suspension works at once.
  • For an API, the SDK's snapshot, key checks and usage reports answer 403, and the portal is unavailable. With the default settings, an SDK that already has a snapshot can serve known keys from it for up to 15 minutes.
  • For an API that sells to its customers through Stripe, their billing is paused, so renewals aren't charged and automatic top ups don't run. It resumes when the suspension is lifted, and the owner's own MicroAuth plan keeps billing as usual.
  • Settings are read only, and the service and its workspace can't change hands.

Users, sessions, refresh tokens, keys and settings are kept during a suspension, and lifting it brings everything back as it was. The owner gets an email both times, and the team's activity log records both.

Retention ​

DataKept for
Accounts, workspaces and servicesUntil you delete them. Free accounts with no services and no teammates are deleted after 24 months without a sign in, after emails 30 and 7 days before
Users of a sign in serviceUntil they or you delete the account. Their profile photo and API keys go with it
Authorization codes, pushed requests and unfinished external sign insDeleted shortly after they expire
Refresh tokensDeleted once they expire or are revoked
Revoked access tokensTheir ID only, until the token would have expired
Apps people connect, registered or known by a metadata documentRemoved after 30 days without use, unless someone still has a working refresh token for one. Blocked apps are kept so the block holds
API keys your users create90 days after they are revoked or expire
Portal sign ups never approved90 days
Activity log400 days. IP addresses are removed after 90 days
Hourly usage400 days
Usage receipts, used to spot duplicate reportsAbout 45 days
Processed Stripe events30 days, or 180 days if an event was never processed
Queued emailsThe content is removed once sent. Emails that could not be sent are deleted after 30 days
Expired sessions and sign in codesDeleted shortly after they expire
Requests for emailed codes, counted for the limit on codesA day. Each holds a keyed hash of the address and the kind of code, and the time it was asked for. The address itself isn't stored
Invites30 days after they are accepted or expire
Revoked keysWorkspace API keys, 30 days after they are revoked. Customer keys, 400 days after, once their hourly usage is gone
Transfers of a service or workspace30 days after they are accepted, declined, canceled or expire
Reports of abuse400 days after they are closed. The reporter's email is removed after 90 days
Ledger entries and payment recordsAs long as the account exists
Card fingerprints from free trialsFor an API's plans, until the API is deleted. For MicroAuth's own plans, with no age limit. Each is Stripe's fingerprint of a card that started a trial, never the card number, and is what stops the card from starting another one
Database backups14 days on the server, taken daily, checked after each run and encrypted. An off-site copy will follow once that storage is set up

Deleting an account, or erasing a portal customer, replaces the person's name and email in the activity log and ledger with a label such as "Deleted user 4f2a9c". See Privacy and your customers for the tools, and the privacy policy for what we collect.

Reporting a vulnerability ​

Email hello@microauth.com and start the subject with "Security". Please leave working credentials, your customers' data and unrelated personal data out of the first message. Security reports are read first.

MicroAuth is a product of Zyref, LLC.