Build

Routers & Prefixes

Which get_*_router factories to mount and how prefixes work.

OutlabsAuth ships router factories (get_*_router). You choose which ones to mount and under which URL prefix — nothing is mounted automatically.

For a first login only, mount get_auth_router. For an admin console, mount the fuller sets below.

Convention

Pick a base prefix for the auth surface and keep it consistent:

Context	Common base	Auth login path	UI `authApiPrefix`
Quickstart	`/auth`	`/auth/login`	`""` (or auth-only under `/auth`)
Examples	`/v1`	`/v1/auth/login`	`/v1`
Production	`/iam`	`/iam/auth/login`	`/iam`

If you mount get_auth_router(..., prefix="/v1/auth"), set the UI’s authApiPrefix to /v1 (the parent of /auth), not/v1/auth.

OutlabsAuth UI joins apiBaseUrl + authApiPrefix + resource paths. With authApiPrefix: "/v1" it calls /v1/auth/config, /v1/users, /v1/roles, and so on.

Which routers exist?

Imported from outlabs_auth.routers unless noted.

Factory	Typical prefix	Role
`get_auth_router`	`/v1/auth`	Login, register, refresh, logout, password reset, invites, magic link / access code, `GET /config`
`get_users_router`	`/v1/users`	Admin user management + sessions / social
`get_self_service_users_router`	host-chosen	Minimal `/me` + permission names
`get_session_router`	`/v1/auth`	Login / refresh / logout only — not session inventory
`get_roles_router`	`/v1/roles`	Role CRUD and permission assignment
`get_permissions_router`	`/v1/permissions`	Permission catalog
`get_api_keys_router`	`/v1/api-keys`	Personal / self-service API keys
`get_api_key_admin_router`	`/v1/admin/entities`	Entity-anchored key inventory
`get_integration_principals_router`	`/v1/admin`	System integration principals
`get_entities_router`	`/v1/entities`	Entity hierarchy (Enterprise)
`get_memberships_router`	`/v1/memberships`	User–entity memberships (Enterprise)
`get_config_router`	`/v1/config`	Entity-type vocabulary
`get_audit_router`	`/v1/audit-events`	Cross-user audit search

Sessions and social accounts live on get_users_router — Sessions & Audit, OAuth.

OAuth factories (module imports):

Factory	Module
`get_oauth_router`	`outlabs_auth.routers.oauth`
`get_oauth_associate_router`	`outlabs_auth.routers.oauth_associate`

What should I mount?

Minimum (auth only)

main.py

from outlabs_auth.routers import get_auth_router

app.include_router(get_auth_router(auth, prefix="/v1/auth"))

SimpleRBAC + admin UI–friendly

main.py

from outlabs_auth.routers import (
    get_api_keys_router,
    get_auth_router,
    get_integration_principals_router,
    get_permissions_router,
    get_roles_router,
    get_users_router,
)

app.include_router(get_auth_router(auth, prefix="/v1/auth"))
app.include_router(get_users_router(auth, prefix="/v1/users"))
app.include_router(get_roles_router(auth, prefix="/v1/roles"))
app.include_router(get_permissions_router(auth, prefix="/v1/permissions"))
app.include_router(get_api_keys_router(auth, prefix="/v1/api-keys"))
app.include_router(get_integration_principals_router(auth, prefix="/v1/admin"))

EnterpriseRBAC + admin UI–friendly

main.py

from outlabs_auth.routers import (
    get_api_key_admin_router,
    get_api_keys_router,
    get_audit_router,
    get_auth_router,
    get_config_router,
    get_entities_router,
    get_integration_principals_router,
    get_memberships_router,
    get_permissions_router,
    get_roles_router,
    get_users_router,
)

app.include_router(get_auth_router(auth, prefix="/v1/auth"))
app.include_router(get_users_router(auth, prefix="/v1/users"))
app.include_router(get_audit_router(auth, prefix="/v1/audit-events"))
app.include_router(get_api_keys_router(auth, prefix="/v1/api-keys"))
app.include_router(get_api_key_admin_router(auth, prefix="/v1/admin/entities"))
app.include_router(get_integration_principals_router(auth, prefix="/v1/admin"))
app.include_router(get_roles_router(auth, prefix="/v1/roles"))
app.include_router(get_permissions_router(auth, prefix="/v1/permissions"))
app.include_router(get_entities_router(auth, prefix="/v1/entities"))
app.include_router(get_memberships_router(auth, prefix="/v1/memberships"))
app.include_router(get_config_router(auth, prefix="/v1/config"))

Two different “config” endpoints

Endpoint	Router	Purpose
`GET {base}/auth/config`	`get_auth_router`	Preset + feature flags — required for OutlabsAuth UI
`GET/PUT {base}/config/entity-types`	`get_config_router`	Entity-type vocabulary (Enterprise)

When to mount

Router factories resolve auth.deps at call time. Either:

Call auth.prime_fastapi_routing() before include_router(...) at import time, or
Mount inside lifespan after await auth.initialize()

Also call auth.instrument_fastapi(app).

When docs and code disagree, trust live OpenAPI at {your-api}/docs and the examples/ mounts.

Background Maintenance

Run cleanup and sync work safely outside FastAPI processes.

Configuration

Secrets, schema, Redis, cache backends, and CLI.