Skip to content

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.
  • Your app's address, if you know it, like https://app.acme.com. You can leave it empty while you build on your machine.

Click Create service. The sign in pages are live right away, and MicroAuth adds a web application for your app, named after the service.

Your app's settings ​

The ready screen shows a .env with your issuer, the app's client ID and client secret, and a cookie secret made in your browser. Copy it into a .env file next to your app. The client secret is shown only this once. If you lose it, open Applications, pick the app and make a new one.

The app allows these addresses, and the same paths on your app's address when you gave one:

SettingValue
Redirect URIhttp://localhost:8000/auth/callback
Sign out URLhttp://localhost:8000/

To add another app, open Applications and add a web application with the same settings. Add your production addresses next to the local ones when you deploy. See Applications.

Try sign in ​

Before you write any code, open the service's Overview and click Try sign in. You go to your sign in page, sign in as one of your people and come back to the dashboard, which shows what an app gets: the name, email, roles and permissions, and how they signed in. Nobody has signed up yet? Choose Create an account on the sign in page, or invite someone from Users if only invited people can join.

Any member of the workspace can try it. It uses an app MicroAuth keeps for this, which doesn't count toward your plan's applications, and it keeps nothing but those details, for 10 minutes. Activity records each try.

Install the SDK ​

bash
pip install "fastapi[standard]" "microauth-fastapi>=3.1"
bash
# Skip uv init when the folder is already a uv project
uv init
uv add "fastapi[standard]" "microauth-fastapi>=3.1"
bash
# Skip poetry init when the folder is already a Poetry project
poetry init
poetry add "fastapi[standard]" "microauth-fastapi>=3.1"

fastapi[standard] brings the fastapi dev command used below. With uv or Poetry, put uv run or poetry run in front of it.

Add your settings ​

The ready screen's .env already has every value. For an app you added yourself, create a .env file next to your app like this one. The SDK reads it when the variables aren't set in the environment.

bash
# .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:

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

Protect a page ​

python
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 ​

bash
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:

html
<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:

python
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 ​

MicroAuth is a product of Zyref, LLC.