FastAPI quickstart

You will create a sign in service, register a FastAPI app with it and sign in. Then you'll add a permission and check it in a route.

You need Python 3.10 or newer. Using another framework? Any OpenID Connect library works with your sign in service. The OAuth and OpenID Connect reference has the endpoints.

Create a sign in service

Sign up at microauth.com/app/signup, or open the dashboard and click New service. Choose Sign in for your app, then enter:

• Name, for example Acme. People see it on the sign in pages and in emails.
• Sign in address, like acme.microauth.dev. This is your issuer: https://acme.microauth.dev.

Click Create service. The sign in pages are live right away.

Register your app

Open Applications and add a web application with these settings:

Setting	Value
Redirect URI	http://localhost:8000/auth/callback
Sign out URL	http://localhost:8000/

Copy the client ID and the client secret. The secret is shown once, so put it straight into your .env file. Add your production addresses next to the local ones when you deploy. See Applications.

Install the SDK

pip

pip install "fastapi[standard]" "microauth-fastapi>=3.1"

uv

uv add "fastapi[standard]" "microauth-fastapi>=3.1"

Poetry

poetry add "fastapi[standard]" "microauth-fastapi>=3.1"

fastapi[standard] brings the fastapi dev command used below.

Add your settings

Create a .env file next to your app. The SDK reads it when the variables aren't set in the environment.

# .env
MICROAUTH_ISSUER=https://acme.microauth.dev
MICROAUTH_CLIENT_ID=...
MICROAUTH_CLIENT_SECRET=...
MICROAUTH_COOKIE_SECRET=...
MICROAUTH_APP_URL=http://localhost:8000

The cookie secret is yours to make. It encrypts the session cookie and needs at least 32 random bytes:

python -c 'import secrets; print(secrets.token_urlsafe(32))'

Protect a page

from fastapi import Depends, FastAPI
from microauth_fastapi import User, UserAuth

app = FastAPI()
auth = UserAuth(app)  # reads the MICROAUTH_* settings


@app.get("/dashboard")
async def dashboard(user: User = Depends(auth.login_required)):
    return {"hello": user.name, "roles": sorted(user.roles)}

UserAuth(app) adds /auth/login, /auth/signup, /auth/callback, /auth/logout and /auth/me. auth.login_required sends signed out visitors to sign in and brings them back to the page they asked for.

Sign in

fastapi dev main.py

Open http://localhost:8000/dashboard. You land on your sign in page. Click Create an account, sign up, and you're back on /dashboard with your name. http://localhost:8000/auth/me shows everything the app knows about you.

To sign out, post a form to /auth/logout from a page on your site:

<form method="post" action="/auth/logout">
  <button>Sign out</button>
</form>

Check a permission

1. In the dashboard, open Roles and permissions and add a permission named posts:write.
2. Add a role called Editor with that permission.
3. Open Users, pick yourself and give yourself the Editor role.

Then require the permission in a route. Here is main.py with one added:

from fastapi import Depends, FastAPI
from microauth_fastapi import User, UserAuth

app = FastAPI()
auth = UserAuth(app)  # reads the MICROAUTH_* settings


@app.get("/dashboard")
async def dashboard(user: User = Depends(auth.login_required)):
    return {"hello": user.name, "roles": sorted(user.roles)}


@app.post("/posts")
async def create_post(user: User = Depends(auth.require(permissions="posts:write"))):
    return {"created_by": user.id}

People without it get 403. For pages, add redirect=True so signed out visitors go to sign in instead of getting 401. Role changes reach the app the next time the SDK refreshes the session, at most one access token lifetime later, so sign out and in again to see yours right away.

What you have now

• Hosted sign in, sign up and password reset pages with your service's name, plus passkeys and two step verification for your users.
• A session in an encrypted, HttpOnly cookie that refreshes itself and ends when the person signs out or you sign them out.
• Roles and permissions you manage in the dashboard and check in one line.

Next steps

• Add Google, GitHub or your own provider.
• Protect an API that your app or other apps call, with access tokens.
• Let AI clients use your MCP server for your users.
• Put the sign in pages on your own domain.
• Every option is in the SDK reference.