> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Access Manager environment variables

> The environment variables that the Auth and Identity components of Access Manager read, with each default and what it changes.

Access Manager runs two components, **Auth** and **Identity**. The **Component** column says which component reads the variable. Values marked as sensitive are secrets: keep them in your secret store, never in a file in your repository or in an image.

To install or upgrade Access Manager, see the [Access Manager chart README](https://github.com/LerianStudio/helm/tree/main/charts/plugin-access-manager).

## Service

| Variable | Component | Description | Default | Required |
| - | - | - | - | - |
| `SERVER_ADDRESS` | Both | Listen address, such as `:4000`. | — | Yes |
| `ENV_NAME` | Both | Environment name, such as `production`, `staging`, or `local`. It sets the default log level. | — | No |
| `LOG_LEVEL` | Both | Log level: `debug`, `info`, `warn`, or `error`. An invalid value stops the startup. | `info` when `ENV_NAME` is `production`, `staging`, or `uat`. `debug` otherwise. | No |
| `DEPLOYMENT_MODE` | Both | Deployment mode, such as `byoc` or `saas`. With `saas`, the component does not start unless `REDIS_TLS` is `true` and `AUTHORIZER_ADDRESS` uses `https://`. The `/readyz` response reports the value. | `local` | No |
| `SWAGGER_ENABLED` | Auth | Serves the OpenAPI document of Auth. | `true` | No |

## Caradhras connection

Read [Caradhras in Access Manager](https://docs.lerian.studio/en/platform/access-manager/caradhras-in-access-manager.md) for how the two components use the identity backend.

| Variable | Component | Description | Default | Required |
| - | - | - | - | - |
| `AUTHORIZER_ADDRESS` | Both | Base URL of Caradhras. Auth does not start with an `http://` address unless `ENV_NAME` is `development`, `staging`, or `local`. | — | Yes |
| `AUTHORIZER_CLIENT_ID` | Both | Client ID of the Caradhras application that Access Manager uses. | — | Yes |
| `AUTHORIZER_CLIENT_SECRET` | Both | Client secret of that application. Sensitive. | — | Yes |
| `AUTHORIZER_APPLICATION_NAME` | Both | Name of that application in Caradhras. | — | Yes |
| `AUTHORIZER_ORGANIZATION_NAME` | Both | Caradhras organization of a single-tenant installation. | `lerian` | No |
| `MULTI_TENANT_ENABLED` | Both | Turns on multi-tenant mode. Auth does not start when `PLUGIN_AUTH_SSO_STATIC_ORGANIZATION` is also set. | `false` | No |
| `AUTHORIZER_JWT_CERTIFICATE` | Both | Certificate, in PEM, that checks the signature of the tokens Caradhras issues. Without it, the component uses the certificate built into the image. An unusable value stops the startup. | — | No |

## Calls to Caradhras

| Variable | Component | Description | Default | Required |
| - | - | - | - | - |
| `HTTP_CLIENT_TIMEOUT_SEC` | Both | Seconds one call to Caradhras can take. | `30` | No |
| `HTTP_CLIENT_MAX_IDLE_CONNS` | Both | Idle connections kept open. | `100` | No |
| `HTTP_CLIENT_MAX_IDLE_CONNS_PER_HOST` | Both | Idle connections kept open to one host. | Auth: `10`. Identity: `100`. | No |
| `HTTP_CLIENT_IDLE_CONN_TIMEOUT_SEC` | Both | Seconds before the component closes an idle connection. | `90` | No |
| `CIRCUIT_BREAKER_ENABLED` | Both | Turns on the circuit breaker on calls to Caradhras. | `true` | No |
| `CIRCUIT_BREAKER_CONSECUTIVE_FAILURES` | Both | Consecutive failures that open the breaker. | `5` | No |
| `CIRCUIT_BREAKER_FAILURE_RATIO` | Both | Share of failed calls that opens the breaker, such as `0.5`. | `0.5` | No |
| `CIRCUIT_BREAKER_MIN_REQUESTS_FOR_RATIO` | Both | Calls that must happen before the failure ratio applies. | `10` | No |
| `CIRCUIT_BREAKER_INTERVAL_SEC` | Both | Seconds after which the closed breaker clears its counts. | `60` | No |
| `CIRCUIT_BREAKER_TIMEOUT_SEC` | Both | Seconds the breaker stays open before it tries Caradhras again. | `30` | No |
| `CIRCUIT_BREAKER_MAX_REQUESTS_HALF_OPEN` | Both | Calls allowed while the breaker tries Caradhras again. | `3` | No |
| `CIRCUIT_BREAKER_HEALTH_CHECK_INTERVAL_SEC` | Both | Seconds between health checks of Caradhras. | `30` | No |
| `CIRCUIT_BREAKER_HEALTH_CHECK_TIMEOUT_SEC` | Both | Seconds one health check can take. | `10` | No |

## Sign-in

| Variable | Component | Description | Default | Required |
| - | - | - | - | - |
| `MFA_ENABLED` | Auth | Declares that this installation uses multi-factor authentication. With `true` and an empty `MFA_SECRET`, Auth logs an error at startup. Read [MFA deployment requirements](https://docs.lerian.studio/en/platform/access-manager/features/mfa/deployment.md). | `false` | No |
| `MFA_SECRET` | Auth | Secret that Auth signs MFA and passkey sign-in tokens with. Without it, those sign-ins answer `503` with `AUT-0028`. Sensitive. | — | With MFA or passkeys |
| `MFA_SESSION_TTL_SEC` | Auth | Seconds an MFA session stays valid. | `300` | No |
| `MFA_MAX_ATTEMPTS` | Auth | Failed MFA code checks allowed for a user. | `5` | No |
| `MFA_MAX_RESEND_ATTEMPTS` | Auth | New MFA codes a user can request. | `3` | No |
| `PASSKEY_RECENT_AUTH_SEC` | Identity | Maximum age, in seconds, of the caller's token to add or remove a passkey. Read [Passkeys](https://docs.lerian.studio/en/platform/access-manager/features/passkeys/overview.md). | `600` | No |
| `PLUGIN_AUTH_SSO_CALLBACK_URL` | Both | Address of the Console SSO callback, where the identity provider sends the browser back. Use the same value in Auth and Identity. Auth does not start when the value is set and is not an absolute `http` or `https` URL with a path. Read [SSO deployment requirements](https://docs.lerian.studio/en/platform/access-manager/features/sso/deployment.md). | — | With SSO |
| `PLUGIN_AUTH_SSO_STATIC_ORGANIZATION` | Auth | Caradhras organization for every SSO sign-in of a single-tenant installation. Without it, Auth finds the organization from the user's email. | — | No |
| `PLUGIN_AUTH_SSO_PREFLIGHT_ALLOW_INSECURE` | Identity | With `true`, the SSO preflight check can call an identity provider over `http://`. Identity logs a warning at startup while it is on. | `false` | No |
| `PLUGIN_AUTH_SSO_ALLOW_PRIVATE_NETWORKS` | Identity | With `true`, the SSO preflight check and the discovery of an identity provider can reach private network addresses. Identity logs a warning at startup while it is on. | `false` | No |
| `ENABLE_FORGOT_PASSWORD` | Identity | With `true`, Identity serves the two password reset routes. Otherwise they answer `404`. | `false` | No |

## Identity API protection

| Variable | Component | Description | Default | Required |
| - | - | - | - | - |
| `PLUGIN_AUTH_ENABLED` | Identity | With `true` and an address of Auth, Identity sends the caller's token to Auth for the permission check on its protected routes. Otherwise, Identity does not call Auth. | `false` | No |
| `PLUGIN_AUTH_ADDRESS` | Identity | Address of Auth. | — | With `PLUGIN_AUTH_ENABLED=true` |
| `AUTH_REQUIRED` | Identity | With `true`, the protected routes of Identity answer `503` when `PLUGIN_AUTH_ENABLED` is not `true` or `PLUGIN_AUTH_ADDRESS` is empty. Read [Product-level enforcement](https://docs.lerian.studio/en/platform/access-manager/product-level-enforcement.md). | `false` | No |
| `AUTH_M2M_JWKS_URL` | Identity | Address of the key set that Identity uses to check application tokens. Without it, Identity uses `AUTHORIZER_ADDRESS` followed by `/.well-known/jwks`. | — | No |
| `AUTH_M2M_JWKS_REFRESH_INTERVAL` | Identity | How often Identity reloads that key set, as a duration such as `5m`. | `5m` | No |
| `AUTH_JWKS_CACHE_TTL` | Auth | How long Auth keeps the Caradhras key set that it serves to other Lerian services, as a duration such as `5m`. | `5m` | No |
| `MAX_PAGINATION_LIMIT` | Identity | Largest `limit` that a list request accepts. | `100` | No |
| `MAX_PAGINATION_PAGE` | Identity | Largest `page` that a list request accepts. | `1000000` | No |

## Network

Read [Deployment requirements (BYOC)](https://docs.lerian.studio/en/platform/access-manager/features/ip-allowlist/deployment.md) and [Tenant IP allowlist](https://docs.lerian.studio/en/platform/access-manager/product-level-enforcement.md#tenant-ip-allowlist) before you set these variables.

| Variable | Component | Description | Default | Required |
| - | - | - | - | - |
| `TRUSTED_PROXIES` | Both | CIDR ranges of the proxies in front of the component, separated by commas. A malformed value stops the startup. | — | No |
| `PLATFORM_INTERNAL_CIDRS` | Both | CIDR ranges that the platform's own services call Caradhras from, separated by commas. Use the same value in Auth, Identity, and Caradhras. A malformed value stops the startup. | — | No |

## Rate limits

| Variable | Component | Description | Default | Required |
| - | - | - | - | - |
| `RATE_LIMIT_ENABLED` | Both | Turns on the rate limits. | `false` | No |
| `RATE_LIMIT_MAX` | Both | Requests that one client address can make in one window. | `100` | No |
| `RATE_LIMIT_WINDOW_SEC` | Both | Length of that window, in seconds. | `60` | No |
| `RATE_LIMIT_AUTH_MAX` | Auth | Requests per window on the token, refresh, logout, SSO, MFA, and passkey sign-in routes. | `10` | No |
| `RATE_LIMIT_AUTH_WINDOW_SEC` | Auth | Length of that window, in seconds. | `60` | No |
| `RATE_LIMIT_PERMISSION_MAX` | Auth | Requests per window on `/v1/authorize`, `/v1/permissions`, and `/v1/userinfo`. | `60` | No |
| `RATE_LIMIT_PERMISSION_WINDOW_SEC` | Auth | Length of that window, in seconds. | `60` | No |
| `RATE_LIMIT_REDIS_TIMEOUT_MS` | Both | Milliseconds that one rate-limit check waits for Valkey. | `500` | No |

## Valkey

| Variable | Component | Description | Default | Required |
| - | - | - | - | - |
| `REDIS_HOST` | Both | Valkey address as `host:port`. With several addresses separated by commas, the component connects to a cluster, or to Sentinel when `REDIS_MASTER_NAME` is set. | — | Yes |
| `REDIS_MASTER_NAME` | Both | Sentinel master name. | — | With Sentinel |
| `REDIS_PASSWORD` | Both | Valkey password. Sensitive. | — | No |
| `REDIS_DB` | Both | Database number. | `0` | No |
| `REDIS_PROTOCOL` | Both | RESP protocol version. | `3` | No |
| `REDIS_TLS` | Both | Connects to Valkey over TLS. | `false` | With `DEPLOYMENT_MODE=saas` |
| `REDIS_CA_CERT` | Both | CA certificate for that TLS connection, as base64 PEM. | — | No |
| `REDIS_USE_GCP_IAM` | Both | Authenticates to Valkey with Google Cloud IAM instead of a password. | `false` | No |
| `REDIS_SERVICE_ACCOUNT` | Both | Google service account for IAM authentication. | — | With IAM |
| `GOOGLE_APPLICATION_CREDENTIALS` | Both | Google credentials for IAM authentication. Sensitive. | — | With IAM |
| `REDIS_TOKEN_LIFETIME` | Both | Lifetime of the IAM token, in minutes. | `60` | No |
| `REDIS_TOKEN_REFRESH_DURATION` | Both | Minutes between IAM token refreshes. Keep it below `REDIS_TOKEN_LIFETIME`. | `45` | No |
| `REDIS_SCAN_COUNT` | Both | Keys that each scan step reads when the component deletes cached entries by pattern. | `100` | No |

## Auth cache

| Variable | Component | Description | Default | Required |
| - | - | - | - | - |
| `CACHE_TTL_ACCESS_TOKEN` | Auth | Seconds Auth keeps an issued access token in its cache. | `300` | No |
| `CACHE_TTL_USER_INFO` | Auth | Maximum seconds Auth keeps a user's profile in its cache. | `900` | No |
| `CACHE_TTL_USER_PERMISSIONS` | Auth | Maximum seconds Auth keeps a user's permissions in its cache. Auth uses at most `60`. | `1800` | No |
| `CACHE_TTL_ORG_PERMISSIONS` | Auth | Seconds Auth keeps the permissions of an organization in memory. | `15` | No |
| `CACHE_LOADER_TIMEOUT_ORG_PERMISSIONS` | Auth | Seconds Auth waits for Caradhras when it loads the permissions of an organization. | `10` | No |
| `CACHE_MAX_ENTRIES_ORG_PERMISSIONS` | Auth | Organizations that the in-memory cache holds. | `1024` | No |

## License

Read [License Manager](https://docs.lerian.studio/en/platform/licensing/license-manager.md) for both values.

| Variable | Component | Description | Default | Required |
| - | - | - | - | - |
| `LICENSE_KEY` | Both | Your Lerian license key. Sensitive. | — | Yes |
| `ORGANIZATION_IDS` | Both | The organizations that the key covers. | — | Yes |

## Telemetry

| Variable | Component | Description | Default | Required |
| - | - | - | - | - |
| `ENABLE_TELEMETRY` | Both | Sends traces, metrics, and logs through OpenTelemetry. | `false` | No |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Both | Address of the OpenTelemetry collector. | — | With telemetry |
| `OTEL_RESOURCE_SERVICE_NAME` | Both | Service name on the telemetry. | Auth: `plugin-auth`. Identity: `plugin-identity`. | No |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Both | Environment label on the telemetry. | — | No |
| `OTEL_LIBRARY_NAME` | Both | Instrumentation name on the telemetry and the logs. | — | No |

## Service discovery

Both components read the shared `SD_*` service discovery variables in [BYOC configuration essentials](https://docs.lerian.studio/en/reference/byoc-configuration.md). With discovery on, Auth and Identity find Caradhras through Consul, and Identity also finds Auth. When discovery gives no answer, they use `AUTHORIZER_ADDRESS` and `PLUGIN_AUTH_ADDRESS`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.