How user authentication works

A sign in service gives your own apps hosted sign in and sign up pages, OAuth 2.1 and OpenID Connect, roles and permissions, and a place to manage your users. AI clients can connect to your MCP servers through it too, with the person's consent.

People sign in on pages MicroAuth hosts at your sign in address. Your apps never handle passwords. They get tokens through the standard code flow and check them locally, so your requests never pass through MicroAuth.

 your users                 your app with the SDK              MicroAuth
+-------------+   visit    +------------------------+  code   +--------------+
| browser     |----------->| redirect to sign in    |-------->| sign in      |
|             |<-----------| keep an encrypted      |<--------| pages, roles |
+-------------+  session   | session cookie         | tokens  | and tokens   |
                           +------------------------+         +--------------+

The pieces

Piece	What it is
Sign in service	One set of users, sign in pages and settings, at https://<slug>.microauth.dev or your own domain. Its address is the issuer your apps trust
Applications	The apps people sign in to: web apps, single page apps and native apps. Each has a client ID and its own redirect URIs
APIs and MCP servers	The servers that accept access tokens. Each is identified by its URL and exposes a set of permissions
Permissions and roles	Permissions such as posts:write are what your code checks. Roles bundle permissions, and you give roles to people
Users	The people who sign in. You can invite, suspend, sign out and delete them
External sign in	Google, GitHub, or any OpenID Connect or OAuth 2.0 provider you bring

A workspace can hold sign in services next to APIs you sell and internal APIs. Each service has its own MicroAuth plan.

How sign in works

1. A visitor opens a page in your app that needs a signed in user.
2. Your app sends the browser to your sign in service, with a one time code challenge (PKCE).
3. The person signs in or signs up there, with a password, a passkey or an external provider. If they already signed in to another of your apps, they skip this step.
4. MicroAuth sends the browser back to your app's redirect URI with a short lived code.
5. Your server exchanges the code for tokens and starts its own session.

The FastAPI SDK does steps 2, 4 and 5 for you and keeps the session in an encrypted, HttpOnly cookie, so browser JavaScript never holds a token.

Tokens

Token	What it's for	Lifetime
ID token	Tells your app who signed in, and their roles when it asked for them	Read once at sign in and on each refresh
Access token	Calls one of your APIs or MCP servers. A signed JWT your server checks without calling MicroAuth	10 minutes by default, and never more than 10 minutes for apps people connect
Refresh token	Gets new tokens without asking the person again. Changes on every use	Lasts as long as the sign in session, or until the app is disconnected

Roles and permissions are read again on every refresh, so a role you remove, or a suspension, reaches your app within one access token lifetime. Sessions and tokens has the details.

Two sessions, no shared cookie

• The sign in pages keep their own session at your sign in address. That session gives single sign on: someone signed in to one of your apps signs in to the next one with a click.
• Each of your apps keeps its own session, set by your server after the code flow. There's no cookie shared across domains and nothing to set up.

Signing out of an app through the SDK ends both.

What it costs

Sign in services are priced per service, with limits on users and applications and switches for features such as external providers, apps people connect and a custom domain. See pricing and your MicroAuth plan.

Start hereFastAPI quickstartSign people in to a FastAPI app and check their roles.AccessRoles and permissionsDefine what people can do, and check it in your app and APIs.AIAI and MCPLet AI clients use your MCP server for a person, with only the access they approve.