Skip to main content

Configuration

identity-service is configured with environment variables. This page is the full reference. .env.example lists only the required settings; every optional one appears there as a commented-out line with its default, so copy it to .env for local runs and uncomment only what you change. To start a production config, run python manage.py generate_env --host auth.example.com: it prints the required settings with fresh secrets, see Run identity-service. The variable list lives in config/env_registry.py, which renders .env.example (generate_env --example), and a test checks it against the code and this page. Pass the same variables to Docker, Coolify, or your orchestrator in production. Durations accept a bare number of seconds or a suffix: s, m, h, d (for example 5m or 30d).

Required in production​

With DEBUG=false (the Docker image default), identity-service refuses to start without these:

VariablePurpose
SECRET_KEYSigns Django sessions and CSRF tokens. Required in every mode. With DEBUG=false, a key shorter than 50 characters or a known placeholder fails manage.py check --deploy (authapi.E005)
JWT_PRIVATE_KEYRS256 private key that signs tokens, see JWT and JWKS
JWT_ISSUERiss claim, the public identity URL, for example https://auth.example.com
JWT_AUDIENCEaud claim, for example shellui
REDIS_URLShared cache and job broker, see Shared cache (Redis)
ALLOWED_HOSTSComma-separated host names, no scheme, for example auth.example.com. Defaults to localhost,127.0.0.1, so a public host gets 400 until it is listed

Behind TLS, also set CSRF_TRUSTED_ORIGINS to the full HTTPS URL (for example https://auth.example.com) so Django admin and the OAuth confirmation page accept form posts.

Tokens​

VariableDefaultPurpose
JWT_ACCESS_TOKEN_LIFETIME5mAccess token lifetime
JWT_REFRESH_TOKEN_LIFETIME7dRefresh token lifetime
IDENTITY_SESSION_MAX_AGE7dIdentity browser session max-age. Unset uses JWT_REFRESH_TOKEN_LIFETIME. Staff sessions are capped by CLI_STAFF_SESSION_MAX_AGE
PERSONAL_ACCESS_TOKEN_LIFETIME30dLifetime of new personal access tokens
JWT_PUBLIC_KEY, JWT_KEY_IDderivedDerived from the private key when unset
JWT_PREVIOUS_PUBLIC_KEY, JWT_PREVIOUS_KEY_IDemptyPrevious key during a rotation, still published in JWKS
JWT_ACCEPT_HS256_LEGACYfalseAccept HS256 tokens while moving from HS256 to RS256
SELF_SERVICE_ACCOUNT_DELETE_MAX_IAT_AGE5mMaximum age of auth_time for account deletion

Sign-in​

VariableDefaultPurpose
OAUTH_TOKEN_DELIVERYcodecode: one-time shellui_auth_code exchanged with POST /api/v1/oauth/session. fragment is ignored since 0.9.0: tokens are never sent in the URL fragment
OAUTH_SESSION_CODE_TTL_SECONDS120Lifetime of the one-time code
OAUTH_SKIP_CONFIRM_PROVIDERSgoogleProviders that skip the confirmation page, comma-separated. Set it empty to always show the page
OAUTH_ALLOW_LOOPBACK_REDIRECTSsame as DEBUGAllow redirect_to on localhost, 127.0.0.1, and ::1
MAGIC_LINK_ENABLEDtrueTurns every magic link endpoint on or off
MAGIC_LINK_TTL_SECONDS1800Magic link lifetime
MAGIC_LINK_EMAIL_DEFAULT_LANGUAGEenMagic link email language when the request and the user have none
SCIM_ENABLEDtruefalse makes every SCIM URL return 404 (emergency switch)

See OAuth login, Magic link, and SCIM provisioning.

Email​

identity-service sends magic links, invitations, and owner notifications. See Email delivery for how email-service and SMTP fit together.

VariableDefaultPurpose
EMAIL_SERVICE_API_KEYemptyemail-service key (esk_). Unset sends everything over SMTP
EMAIL_SERVICE_URLhttps://email.shellui.comPublic email-service origin (MCP discovery). Local stack: http://localhost:8004, see Local dev stack
EMAIL_SERVICE_INTERNAL_URLemptyServer-to-server email-service origin. Unset uses EMAIL_SERVICE_URL. Local stack: http://email:8000
EMAIL_SERVICE_TIMEOUT_SECONDS5Timeout for one HTTP attempt
EMAIL_SERVICE_SEND_ATTEMPTS3Attempts for one direct send
EMAIL_SERVICE_RETRY_MAX_SLEEP_SECONDS1Longest pause between direct send attempts
EMAIL_BACKENDconsole with DEBUG=true, SMTP otherwiseDjango email backend
EMAIL_HOST, EMAIL_PORTlocalhost, 25SMTP server
EMAIL_HOST_USER, EMAIL_HOST_PASSWORDemptySMTP credentials
EMAIL_USE_TLS, EMAIL_USE_SSLfalseSMTP encryption
DEFAULT_FROM_EMAILnoreply@localhostSender address for SMTP
EMAIL_TIMEOUT10Seconds before an SMTP connect, read, or write gives up. Without it, a silent mail server could hold a sign-in request forever

email-service EMAIL_AUTH_LINK_HOSTS must include the host of JWT_ISSUER.

Webhooks​

VariableDefaultPurpose
ACTIONS_WEBHOOK_TIMEOUT_SECONDS5Timeout of one webhook POST
ACTIONS_OUTBOX_MAX_ATTEMPTS8Delivery attempts before a delivery fails
ACTIONS_WEBHOOK_ALLOW_PRIVATEfalseAllow webhooks to private IP addresses
ACTIONS_WEBHOOK_RETRY_LEASE_SECONDS120How long a retry worker holds a delivery
ACTIONS_WEBHOOK_DISPATCH_WORKERS4Threads that send webhooks after the database commit
ACTIONS_WEBHOOK_SYNC_DELIVERYfalseSend webhooks inline in the request instead of in background threads. For tests only

See Webhooks.

Shared cache (Redis)​

VariableDefaultPurpose
REDIS_URLunsetRequired with DEBUG=false since 0.7.0. Holds rate limits, the logout denylist, OAuth PKCE state, SAML request IDs and replay protection, and last-seen throttling. Also the broker of the scheduled jobs

With DEBUG=false, the container refuses to start without REDIS_URL, also with SCHEDULER_ENABLED=false or CELERY_BROKER_URL set, because the cache and the OAuth and SAML state need it. In web and worker mode the entrypoint exits with status 1 before migrations:

entrypoint: ERROR: REDIS_URL is required when DEBUG is false (example: redis://redis:6379/0).

manage.py check --deploy reports the same problem as authapi.E004. Other container commands, such as createsuperuser, and the test suite still run.

With DEBUG=true, REDIS_URL is optional: Django uses an in-process cache, and the container logs a warning and runs without the scheduled jobs.

# Redis next to identity-service in Docker Compose or Coolify
REDIS_URL=redis://redis:6379/0

PUBLISH.md describes the Redis setup on Coolify.

Scheduled jobs​

The Docker image runs retry_webhooks every minute and purge_expired_data every hour, in a Celery worker next to gunicorn. With REDIS_URL set, there is nothing else to configure. See Scheduled jobs for several replicas and external cron.

VariableDefaultPurpose
SCHEDULER_ENABLEDtrueStart the worker in the web container. Set false when a worker container or your own cron runs the jobs
CELERY_BROKER_URLREDIS_URLA different broker for the jobs
CELERY_WORKER_CONCURRENCY2Worker threads, so the hourly purge and a webhook retry can run together
CELERY_BEAT_SCHEDULE_FILE/tmp/celerybeat-scheduleWhere Celery beat keeps its schedule state (Docker entrypoint)

The container command picks what runs: web (default: migrations, gunicorn, and the worker), worker (the worker only, no migrations), or any other command, run as appuser.

Database​

VariableDefaultPurpose
POSTGRES_DATABASE_URLemptyPostgreSQL DSN. Unset uses SQLite
SQLITE_PATHdb.sqlite3, /app/data/db.sqlite3 in DockerSQLite file
POSTGRES_SSL_REQUIREtrue with DEBUG=falseRequire TLS to PostgreSQL
POSTGRES_CONNECT_TIMEOUT10Seconds, so workers do not hang on a dead connection
POSTGRES_STATEMENT_TIMEOUT15Seconds before PostgreSQL cancels a query. 0 turns it off. Not applied to migrate
POSTGRES_LOCK_TIMEOUT5Seconds before PostgreSQL stops waiting for a lock. 0 turns it off. Not applied to migrate

SQLite runs in WAL mode for better concurrency on a single node. With PostgreSQL, connections that died while idle are replaced before the next request uses them.

For load balancer health checks, use GET /health/live. It touches neither the session nor the database. The Docker image already runs it as its HEALTHCHECK, so Coolify needs no health check config.

Gunicorn (Docker entrypoint)​

VariableDefaultPurpose
GUNICORN_WORKERS4Worker processes
GUNICORN_THREADS4Threads per worker (gthread worker class)
GUNICORN_TIMEOUT60Seconds of silence before gunicorn restarts a frozen worker process. See the note below
GUNICORN_GRACEFUL_TIMEOUT30Seconds a worker gets to finish open requests on restart or shutdown
GUNICORN_KEEP_ALIVE75Seconds an idle keep-alive connection stays open. Keep it above the reverse proxy idle timeout to avoid random 502 errors
GUNICORN_MAX_REQUESTS1000Restart a worker after this many requests. 0 turns it off
GUNICORN_MAX_REQUESTS_JITTER200Random extra requests added to GUNICORN_MAX_REQUESTS, so workers do not all restart at once

Concurrency is about workers × threads. A pool that is too small queues requests while OAuth calls hold threads.

GUNICORN_TIMEOUT does not stop a stuck request

With the gthread worker class, a worker keeps sending heartbeats while one of its threads is blocked (on SMTP, the database, or an outbound HTTP call), so gunicorn never kills it. Requests sent to that worker can wait with no response and no log line. Request deadlines come from the app instead: EMAIL_TIMEOUT, POSTGRES_STATEMENT_TIMEOUT, POSTGRES_LOCK_TIMEOUT, and the 20 second OAuth HTTP timeouts. Set a response timeout on the reverse proxy too. GUNICORN_MAX_REQUESTS also recycles workers over time.

The entrypoint sets --worker-tmp-dir /dev/shm (the heartbeat file lives in memory) and writes the gunicorn access and error logs to stdout. Each access log line ends with the duration and the request ID, for example "GET /api/v1/settings HTTP/1.1" 200 512 "Mozilla/5.0" 182ms req=4f2c9a1e. Lines have the path without the query string and no Referer, because query strings carry magic link tokens, OAuth codes, confirm_token, and setup_token.

Security​

VariableDefaultPurpose
TRUSTED_PROXY_IPSemptyReverse proxies allowed to set X-Forwarded-For (IPs or CIDR ranges)
CORS_ALLOW_ALL_ORIGINStrueAllow API calls from any shell origin, without credentials
CORS_ALLOW_CREDENTIALSfalseMust stay false while CORS_ALLOW_ALL_ORIGINS=true
CORS_ALLOWED_ORIGINS, CORS_ALLOWED_ORIGIN_REGEXESemptyAllowed origins when CORS_ALLOW_ALL_ORIGINS=false
AUTH_RATE_LIMIT_ENABLEDtrueTurn rate limits off, for debugging only
AUTH_RATE_LIMIT_OAUTH30OAuth requests per minute
AUTH_RATE_LIMIT_MCP_REGISTER10MCP dynamic client registrations per hour, per client IP
AUTH_RATE_LIMIT_MCP_SIGNIN30MCP sign-in page requests per 5 minutes, per client IP
AUTH_RATE_LIMIT_TOKEN_REFRESH60Token refreshes per minute
AUTH_RATE_LIMIT_SETTINGS30GET /api/v1/settings per minute
AUTH_RATE_LIMIT_MAGIC_LINK10Magic link requests per minute
AUTH_RATE_LIMIT_TOKEN_EXCHANGE30Token exchange requests per minute, per client IP
AUTH_RATE_LIMIT_PAT30Personal access token requests per minute
AUTH_RATE_LIMIT_ADMIN_LOGIN10Django admin sign-ins per 5 minutes
AUTH_RATE_LIMIT_INVITATION30Invitations per 5 minutes per company
AUTH_RATE_LIMIT_MCP_PERSONAL_AGENT10Personal MCP agent token creations per hour, per user
AUTH_RATE_LIMIT_MCP_DEVICE_CODE30Device authorization requests per 5 minutes, per client IP
AUTH_RATE_LIMIT_MCP_DEVICE_VERIFY8Device user-code attempts per 5 minutes, per client IP
AUTH_RATE_LIMIT_CLI_DEVICE_CODE30CLI device authorization requests per 5 minutes, per client IP
AUTH_RATE_LIMIT_CLI_DEVICE_VERIFY8CLI device user-code and password attempts per 5 minutes, per client IP
CLI_STAFF_SESSION_MAX_AGE12hCap for a staff Shellui CLI refresh token and for a staff identity browser session. Non-staff CLI refresh tokens use JWT_REFRESH_TOKEN_LIFETIME
MCP_DYNAMIC_CLIENT_REGISTRATIONtrueMCP OAuth dynamic client registration
MCP_ACCESS_TOKEN_LIFETIME15mMCP agent access JWT lifetime
MCP_REFRESH_TOKEN_LIFETIME30dMCP agent refresh token lifetime
MCP_PERSONAL_AGENT_MAX_LIFETIME_DAYS90Maximum lifetime for personal MCP bearer tokens and for device-login agents
MCP_DEVICE_CODE_LIFETIME_SECONDS600How long a device code stays valid (clamped 60 to 1800)
MCP_DEVICE_CODE_INTERVAL_SECONDS5Minimum seconds between device-code token polls (clamped 5 to 60)
MCP_AGENT_ACTIVITY_RETENTION_DAYS90How long member activity logs are kept for personal MCP agents
MCP_APPROVAL_SESSION_TTL_SECONDS60Seconds a client "Allow for this session" grant lasts (clamped 30 to 60) for non-destructive MCP writes
MCP_APPROVAL_ASSERTION_MAX_LIFETIME_SECONDS900Maximum exp - iat Identity accepts on internal MCP approval assertions from ai-service only (600 to 900 second setup flows); other issuers stay at 60 seconds; shellui-django defaults to 60
MCP_APPROVAL_SETUP_SESSION_TTL_MIN_SECONDS600Lower bound for mcp_session_ttl_seconds on ai-service assertions with setup_flow when extending session Allow
MCP_APPROVAL_SETUP_SESSION_TTL_MAX_SECONDS900Upper bound for the same
MCP_RATE_LIMIT_AGENT120MCP tool calls per minute per agent
SECURE_SSL_REDIRECT, SESSION_COOKIE_SECURE, CSRF_COOKIE_SECUREtrue with DEBUG=false, false with DEBUG=trueHTTPS defaults. Secure cookies are named __Host-sessionid and __Host-csrftoken, with no Domain. On HTTP, a region uses shellui_region_sessionid / shellui_region_csrftoken and a global instance uses shellui_global_sessionid / shellui_global_csrftoken. Standalone HTTP keeps sessionid and csrftoken. CSRF_COOKIE_HTTPONLY is always on
SECURE_HSTS_SECONDS31536000 with DEBUG=false, 0 with DEBUG=trueHSTS max-age
SECURE_HSTS_INCLUDE_SUBDOMAINStrue with DEBUG=falseAdd includeSubDomains to HSTS
SECURE_HSTS_PRELOADfalseAdd preload to HSTS

See Security hardening for the rate limit defaults, proxies, and CORS.

Runtime and observability​

VariableDefaultPurpose
DEBUGfalseOptional. Unset or empty means false, so production does not need to set it. Set true only for local development (.env.example and docker-compose.yml do). Required in .env.example for local runs
SETUP_TOKENemptyOne-time token for the web form that creates the first superuser with DEBUG=false. Prefer createsuperuser
IDENTITY_DEV_SEEDfalseLocal dev only. With DEBUG=true, the dev entrypoint runs manage.py seed_dev (company 1, admin / admin, dev@localhost). Never set in production
IDENTITY_DEV_PUBLIC_HOSTemptyLocal dev only. Hostname seed_dev adds to the OAuth redirect origins, on the same ports as localhost, so a LAN or Tailscale browser can sign in. Never set in production
IDENTITY_SERVICE_PORT8000Host port in docker-compose.yml only
LOG_LEVELINFO, DEBUG with DEBUG=trueApp log level on stdout. Django errors and warnings (500 errors, DisallowedHost, CSRF failures) are always printed
SLOW_REQUEST_THRESHOLD_SECONDS2Log a warning for slower requests. 0 turns it off
SENTRY_DSNemptyTurns on Sentry error reporting. No personal data is sent
SENTRY_ENVIRONMENTproduction, development with DEBUG=trueSentry environment tag
SENTRY_RELEASEpackage versionSentry release tag
SENTRY_TRACES_SAMPLE_RATE0Share of requests traced. 0 reports errors only; 0.1 shows slow requests
SHELLUI_GEOIP_DATABASE_PATHemptyMaxMind GeoLite2 City file (.mmdb), adds country and city to sign-in events. Also needs the optional geoip2 package, which the image does not include

Instance role​

Leave SHELLUI_INSTANCE_ROLE unset for a standalone deployment. global turns this process into an OpenID Provider. region trusts the global identity server for browser sign-in and user token exchange, using GLOBAL_ISSUER_URL, a pinned GLOBAL_JWKS, and GLOBAL_CLIENT_ID / GLOBAL_CLIENT_SECRET. Global MCP agent tokens can use a second issuer: set GLOBAL_AGENT_ISSUER_URL and GLOBAL_AGENT_JWKS, or leave both empty to verify those tokens with GLOBAL_ISSUER_URL and GLOBAL_JWKS. Endpoints, assertions, and the production host check are in Instance roles. Agent exchange is in MCP and agents.

VariableDefaultPurpose
SHELLUI_INSTANCE_ROLEunsetglobal, region, or unset
OIDC_CLIENTSemptyJSON list of confidential clients, provider role
OIDC_CORS_ALLOWED_ORIGINSemptyOrigins allowed on the OpenID endpoints. The Bearer API is unchanged
OIDC_SESSION_TTL_SECONDS43200Provider browser-session lifetime
OIDC_CODE_TTL_SECONDS60Authorization code lifetime
OIDC_ID_TOKEN_TTL_SECONDS300id_token lifetime
OIDC_BACKCHANNEL_TIMEOUT_SECONDS3Back-channel logout POST timeout
GLOBAL_ISSUER_URLemptyUpstream issuer, relying party role (browser redirects and iss validation)
GLOBAL_ISSUER_INTERNAL_URLemptyBase URL for server-side calls to the upstream token endpoint. Unset uses GLOBAL_ISSUER_URL. Local stack: http://identity:8000 on a regional server
GLOBAL_JWKSemptyPinned upstream JWKS JSON
GLOBAL_CLIENT_ID, GLOBAL_CLIENT_SECRETemptyUpstream client credentials
GLOBAL_REDIRECT_URI{JWT_ISSUER}/oauth/upstream-callbackUpstream redirect URI when the public URL differs
GLOBAL_ACCESS_TOKEN_AUDIENCEemptyaud of global access tokens (the global server's JWT_AUDIENCE). Turns on token exchange at POST /oauth/token. Empty answers 404
GLOBAL_AGENT_ACCESS_TOKEN_AUDIENCEemptyaud of global MCP agent access tokens. Turns on agent token exchange at POST /oauth/token (MCP authorization server token_endpoint; POST /oauth/mcp/token is the same handler). Empty answers 404
GLOBAL_AGENT_ISSUER_URLemptyiss of those agent tokens: the saas-service public URL. Empty uses GLOBAL_ISSUER_URL. User token exchange ignores it
GLOBAL_AGENT_JWKSemptyPinned JWKS JSON for GLOBAL_AGENT_ISSUER_URL. Empty uses GLOBAL_JWKS. Keys are not fetched. User token exchange ignores it
PROVISIONING_PUBLIC_KEYemptyDashboard provisioning public key (PEM), region role. Empty turns the provisioning API off
PROVISIONING_KEY_IDemptyExpected assertion kid when set
PROVISIONING_ISSUERemptyExpected assertion iss (the dashboard)
PROVISIONING_AUDIENCEhost of JWT_ISSUERExpected assertion aud
PROVISIONING_DEFAULT_REDIRECTSemptyOrigins added to each provisioned company's redirect allowlist
STORAGE_SERVICE_URLemptyPublic storage-service origin (MCP list_services). Unset: skipped with a warning for deletion
STORAGE_SERVICE_INTERNAL_URLemptystorage-service origin for company-deletion HTTP. Unset uses STORAGE_SERVICE_URL. See Company deletion
HOSTING_SERVICE_URLemptyPublic hosting-service origin (MCP list_services)
HOSTING_SERVICE_INTERNAL_URLemptyhosting-service origin for company-deletion HTTP. Unset uses HOSTING_SERVICE_URL
SAAS_SERVICE_URLemptysaas-service (dashboard) origin for MCP list_services
AI_SERVICE_URLemptyai-service origin for MCP connector, list_services, and approval decide wake (POST /internal/mcp-approval-decided)
AI_SERVICE_ISSUERAI_SERVICE_URLExpected iss on ai-service downstream token delegation JWTs
AI_SERVICE_JWKSemptyPinned JWKS JSON for ai-service (alternative to fetching AI_SERVICE_JWKS_URL)
AI_SERVICE_JWKS_URL{AI_SERVICE_URL}/.well-known/jwks.jsonJWKS URL when AI_SERVICE_JWKS is unset
AI_SERVICE_JWKS_TIMEOUT_SECONDS10HTTP timeout when fetching ai-service JWKS
STORAGE_SERVICE_ISSUERemptyExpected iss on internal MCP assertions signed by storage-service. Unset means storage-service is not trusted
STORAGE_SERVICE_JWKSemptyPinned JWKS JSON for storage-service (alternative to fetching STORAGE_SERVICE_JWKS_URL)
STORAGE_SERVICE_JWKS_URL{STORAGE_SERVICE_INTERNAL_URL or STORAGE_SERVICE_URL}/.well-known/jwks.jsonJWKS URL when STORAGE_SERVICE_JWKS is unset
HOSTING_SERVICE_ISSUERemptyExpected iss on internal MCP assertions signed by hosting-service. Unset means hosting-service is not trusted
HOSTING_SERVICE_JWKSemptyPinned JWKS JSON for hosting-service (alternative to fetching HOSTING_SERVICE_JWKS_URL)
HOSTING_SERVICE_JWKS_URL{HOSTING_SERVICE_INTERNAL_URL or HOSTING_SERVICE_URL}/.well-known/jwks.jsonJWKS URL when HOSTING_SERVICE_JWKS is unset
EMAIL_SERVICE_ISSUERemptyExpected iss on internal MCP assertions signed by email-service. Unset means email-service is not trusted
EMAIL_SERVICE_JWKSemptyPinned JWKS JSON for email-service (alternative to fetching EMAIL_SERVICE_JWKS_URL)
EMAIL_SERVICE_JWKS_URL{EMAIL_SERVICE_INTERNAL_URL or EMAIL_SERVICE_URL}/.well-known/jwks.jsonJWKS URL when EMAIL_SERVICE_JWKS is unset
INTERNAL_CALLER_JWKS_TIMEOUT_SECONDS10HTTP timeout when fetching a caller JWKS
MCP_RATE_LIMIT_DOWNSTREAM_MINT300Global per-minute cap on downstream access token mint requests
COMPANY_DELETION_TIMEOUT_SECONDS10Timeout of each call to those services
DASHBOARD_WEBHOOK_URLemptysaas-service region webhook (https://<dashboard>/api/v1/webhooks/<region>) that receives identity.company.deleted
DASHBOARD_WEBHOOK_INTERNAL_URLemptyServer-to-server URL for that webhook POST. Unset uses DASHBOARD_WEBHOOK_URL
DASHBOARD_WEBHOOK_SECRETemptySigning secret for that webhook. Same value as the region's webhook secret in saas-service
DASHBOARD_PUBLIC_URLemptyOptional public Shellui dashboard origin (https://…, path-less). When set, GET /api/v1/mcp/personal/status includes global_mcp_url as {DASHBOARD_PUBLIC_URL}/mcp for global account MCP discovery. Independent of regional mcp_url