Build

Configuration

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

Knobs you set when embedding OutlabsAuth. The full field list lives in outlabs_auth/core/config.py (AuthConfig).

New install? Start with Getting Started, then come back here for production defaults.

Required

Setting	How	Notes
Database URL	`database_url=` or `DATABASE_URL` for CLI	Must be `postgresql+asyncpg://...`
JWT secret	`secret_key=` or `SECRET_KEY`	≥ 32 characters for HS256

Recommended production baseline

main.py

from outlabs_auth import EnterpriseRBAC  # or SimpleRBAC

auth = EnterpriseRBAC(
    database_url="postgresql+asyncpg://user:password@db-host/app?ssl=require",
    database_schema="outlabs_auth",
    secret_key="...",  # long random secret
    auto_migrate=False,
    redis_url="redis://cache-host:6379/0",
)

Setting	Guidance
`database_schema`	Keep auth tables in a dedicated schema
`auto_migrate`	`False` in multi-worker runtime; migrate via CLI in prestart
`redis_url`	Counters, rate limits, shared permission caching
`cache_backend`	`redis` (multi-instance), `memory` (single-process), or `none`
`background_job_mode`	`"disabled"` in production APIs; use one external maintenance owner
Mount prefix	App-owned — keep consistent with UI `authApiPrefix`

Permission cache backends

Backend	When to use
`redis`	Multi-instance / multi-worker production
`memory`	Single-process hosts without Redis
`none`	No cross-request permission cache

main.py

# Single-instance, no Redis
auth = SimpleRBAC(
    database_url=...,
    secret_key=...,
    cache_backend="memory",
)

Do not use memory when multiple workers must see each other's permission invalidations immediately — use redis instead.

background_job_mode accepts "disabled" (the default) or "embedded". Production API processes should remain disabled while one explicit scheduler or worker calls run_maintenance_once(). Embedded mode is a single-process development convenience.

TaskQ, Celery, and Cron are host integrations—not library modes. See Background Maintenance for the CLI and programmatic entry points, retries, activation, and rollback.

Feature flags

Flag	SimpleRBAC	EnterpriseRBAC
`enable_entity_hierarchy`	forced off	forced on
`enable_context_aware_roles`	forced off	optional (default off)
`enable_abac`	forced off	optional (default off)

Flag	Default	Purpose
`enable_invitations`	`True`	Invite-by-email flow
`enable_magic_links`	`False`	Passwordless magic links
`enable_access_codes`	`False`	Passwordless access codes
`store_refresh_tokens`	`True`	DB-backed refresh revocation (session inventory)
`enable_token_blacklist`	`False`	Immediate access-token blacklist (Redis)

enable_audit_log is a legacy feature-status flag — it does not gate session/audit HTTP routes. Passwordless walkthrough: Passwordless & Messaging. ABAC: ABAC.

CLI target and credentials

Contexts store non-secret target metadata. Human bearer sessions live in a separate owner-only store, while API keys and one-off bearer credentials should come from environment variables or a secret manager.

Variable	Purpose
`DATABASE_URL`	Direct Postgres URL for local database commands
`OUTLABS_AUTH_SCHEMA`	Database schema for migrations and maintenance
`OUTLABS_AUTH_BOOTSTRAP_*`	Optional first-admin inputs for non-interactive bootstrap
`OUTLABS_AUTH_CONFIG`	Alternate non-secret context file
`OUTLABS_AUTH_CREDENTIALS`	Alternate owner-only human session file
`OUTLABS_AUTH_PROFILE`	Context selected for an invocation
`OUTLABS_AUTH_BASE_URL`	One-off remote base URL override
`OUTLABS_AUTH_API_PREFIX`	One-off mounted API-prefix override
`OUTLABS_AUTH_CREDENTIAL_TYPE`	One-off transport override: `bearer` or `api-key`
`OUTLABS_AUTH_CREDENTIAL_ENV`	One-off name of the environment variable containing the credential
`OUTLABS_AUTH_TOKEN`	Default remote bearer credential
`OUTLABS_AUTH_API_KEY`	Default remote API-key credential
`OUTLABS_AUTH_OUTPUT`	Default output contract: `text` or `json`
`OUTLABS_AUTH_NON_INTERACTIVE`	Disable prompts for automation
`OUTLABS_AUTH_TIMEOUT`	Remote HTTP timeout in seconds
`OUTLABS_AUTH_DEBUG`	Include tracebacks for unexpected CLI failures

Terminal

outlabs-auth context add production \
  --base-url https://api.example.com \
  --api-prefix /iam
outlabs-auth auth login --email admin@example.com
outlabs-auth capabilities
outlabs-auth whoami

The Command Line guide covers complete UI-optional administration, secret-safe key creation, coding-agent discovery, stable JSON and exit contracts, and declarative plan/apply.

Local operator commands

Terminal

outlabs-auth migrate
outlabs-auth seed-system
outlabs-auth bootstrap-admin
outlabs-auth doctor
outlabs-auth bootstrap
outlabs-auth run-maintenance
outlabs-auth tables
outlabs-auth current

run-maintenance prints a typed maintenance report. Exit 0 means every configured step completed without reported errors; exit 1 means the report is incomplete or error-bearing.