Configurations
Using environment variables, you can configure the PDP to suit your needs.
Since the PDP uses OPAL under the hood, all of OPAL Configurations are also available with a OPAL_ prefix.
PDP specific configurations are available with a PDP_ prefix.
PDP versions follow Semantic Versioning conventions. Hence, minor versions (e.g., 1.2.3 to 1.2.4) do not introduce breaking changes. For further details and more information, see SemVer
PDP Configurations
PDP_API_KEY
Default: MUST BE DEFINED
The API key used to authenticate the PDP against Permit.io. See more details about API Keys
This is a required configuration. The key must be an Environment-level API Key.
PDP_CONTROL_PLANE
Default: https://api.permit.io
The URL of the Permit.io control plane.
PDP_CONTROL_PLANE_TIMEOUT
Default: 75
Timeout in seconds for control plane requests. This includes proxied requests for the Consistent Updates APIs.
PDP_DEBUG
Default: None
Enables debug mode, which injects debug attributes to OPA policy queries. The available configurations are:
PDP_DEBUG=None- The default behavior - will use the configuration set by Permit.io Cloud.PDP_DEBUG=True- Will enable Debug Mode for this specific PDP.PDP_DEBUG=False- Will disable Debug Mode for this specific PDP.
Turning on Debug Mode will impact policy evaluation latency. Thus, it is recommended to disable Debug Mode when running in production.
For more detailed configuration about the PDP Debug Mode, please check the full documentation here.
PDP_PORT
Default: 7766
The port the PDP server will listen on.
Added in PDP v0.9.0
use UVICORN_PORT for PDP versions prior to v0.9.0
PDP_HEALTHCHECK_TIMEOUT
Default: 3
Timeout in seconds for health checks. This controls how long the PDP will wait for health check responses before timing out.
PDP_USE_NEW_AUTHORIZED_USERS
Default: false
Feature flag for enabling the new authorized users implementation. This feature is controlled by the control plane.
Added in PDP v0.9.0
PDP_SHARD_ID
Default: None
The shard id of this PDP, used to identify the PDP in the control plane
PDP_CONTROL_PLANE_PDP_DELTAS_API
Default: https://pdp-deltas.api.permit.io
The URL of the Permit.io PDP Deltas API.
This configuration is controlled by Permit.io, changing it can cause your PDP to malfunction.
PDP_CONTROL_PLANE_RELAY_API
Default: https://opal-relay.api.permit.io
The URL of the Permit.io Relay API.
This configuration is controlled by Permit.io, changing it can cause your PDP to malfunction.
PDP_CONTROL_PLANE_RELAY_JWT_TIER
Default: https://relay-jwt.api.permit.io
The URL of the Permit.io Relay JWT API.
This configuration is controlled by Permit.io, changing it can cause your PDP to malfunction.
PDP_BACKEND_SERVICE_URL
Default: https://api.permit.io/v2
The Permit.io service URL where proxy requests are sent.
This configuration is controlled by Permit.io, changing it can cause your PDP to malfunction.
PDP_BACKEND_LEGACY_URL
Default: https://api.permit.io/sdk
The legacy Permit.io service URL where proxy requests are sent.
This configuration is controlled by Permit.io, changing it can cause your PDP to malfunction.
PDP_REMOTE_CONFIG_ENDPOINT
Default: /v2/pdps/me/config
The control plane route to fetch policy data topics.
PDP_REMOTE_STATE_ENDPOINT
Default: /v2/pdps/me/state
The control plane route to push state changes.
PDP_DECISION_LOG_DEBUG_INFO
Default: True
Log verbose debug information about decision logs.
PDP_PRINT_CONFIG_ON_STARTUP
Default: False
Print the PDP configuration on startup.
PDP_ENABLE_MONITORING
Default: False
Enables Datadog APM tracing.
PDP_CENTRAL_LOG_DRAIN_URL
Default: https://listener.logz.io:8071
The URL for centralized logging.
PDP_CENTRAL_LOG_DRAIN_TIMEOUT
Default: 5
The timeout for the centralized log drain, in seconds.
PDP_CENTRAL_LOG_TOKEN
Default: None
The token used for centralized logging.
PDP_CENTRAL_LOG_ENABLED
Default: False
Forward logs to the centralized logging service.
This feature is deprecated and will be removed in future versions.
PDP_PING_INTERVAL
Default: 10
The interval for pinging the control plane, in seconds.
PDP_OPA_CLIENT_QUERY_TIMEOUT
Default: 1
The timeout for querying OPA for an allow decision, in seconds. 0 means no timeout.
PDP_OPA_CLIENT_FAILURE_THRESHOLD
Default: 0.1
The percentage of failed requests to OPA that will trigger a failure, causing the healthcheck to fail.
PDP_OPA_CLIENT_FAILURE_THRESHOLD_INTERVAL
Default: 60
The interval to calculate the failure threshold, in seconds.
PDP_OPA_CONFIG_FILE_PATH
Default: ~/opa/config.yaml
The path on the container for OPA config file.
PDP_OPA_AUTH_POLICY_FILE_PATH
Default: ~/opa/basic-authz.rego
The path on the container for OPA authorization policy (rego file).
PDP_OPA_BEARER_TOKEN_REQUIRED
Default: True
If true, all API calls to OPA must provide a bearer token (the value of CLIENT_TOKEN).
PDP_OPA_DECISION_LOG_ENABLED
Default: True
If true, OPA decision logs will be uploaded to the Permit.io cloud console.
PDP_OPA_DECISION_LOG_CONSOLE
Default: False
If true, OPA decision logs will also be printed to console (only relevant if OPA_DECISION_LOG_ENABLED is true).
PDP_OPA_DECISION_LOG_INGRESS_ROUTE
Default: /v2/decision-logs/ingress
The route on Permit.io the decision logs will be uploaded to.
PDP_OPA_DECISION_LOG_INGRESS_BACKEND_TIER_URL
Default: https://decision-log-ingress.api.permit.io
The URL that decision logs will be uploaded to. Automatically configured by the control plane.
PDP_OPA_DECISION_LOG_MIN_DELAY
Default: 1
The minimum amount of time (in seconds) to wait between decision log uploads.
When unable to upload logs, the PDP performs an exponential backoff up to PDP_OPA_DECISION_LOG_MAX_DELAY until a successful upload.
PDP_OPA_DECISION_LOG_MAX_DELAY
Default: 10
The maximum amount of time (in seconds) to wait between decision log uploads.
PDP_OPA_DECISION_LOG_UPLOAD_SIZE_LIMIT
Default: 65536
Log upload size limit in bytes. OPA will chunk uploads to cap message body to this limit.
PDP_ALLOW_METRICS_UNAUTHENTICATED
Default: False
If true, the /metrics endpoint will be accessible without authentication.
PDP_ALLOW_UNAUTHENTICATED_TRINO
Default: False
Expose the Trino authorization endpoints without requiring PDP authentication. When enabled, clients can reach the Trino routes without presenting an API key.
Trino does not currently support passing an API key or credentials when calling external authorization endpoints.
As a result, you must expose the PDP's Trino authorization routes (such as /trino/allowed, /trino/row-filter, /trino/batch-column-masking) without authentication, by setting PDP_ALLOW_UNAUTHENTICATED_TRINO=True.
Because these endpoints are unauthenticated, do not expose your PDP to the public internet or any untrusted networks. Always deploy the PDP behind a firewall or within a secure, trusted network accessible only by the Trino cluster.
For more information, follow the Trino issue on this topic.
PDP_TRINO_AUTHZ_CONFIG_PATH
Default: /app/config/trino-authz.yaml
Absolute path to the YAML file that defines Trino row filters and column masking policies loaded by the PDP. If the file is absent or fails to parse, the PDP starts without additional Trino authorization rules.
For more information, see the Trino integration documentation.
PDP_LOCAL_FACTS_WAIT_TIMEOUT
Default: 10
When using SDK proxy facts via PDP, the default time to wait for the facts to be available, in seconds.
PDP_TEMP_LOG_FORMAT
Default: <green>{time}</green> | {process} | <blue>{name: <40}</blue>|<level>{level:^6} | {message}</level>
Change this parameter to change the log format (e.g. remove colors).
PDP_LOCAL_FACTS_TIMEOUT_POLICY
Default: ignore
The policy to use when the PDP fails to apply a data update within the timeout period.
ignore: Respond immediately when data update did not apply within the timeout periodfail: Respond with 424 status code when data update did not apply within the timeout period
PDP_DATA_UPDATE_CALLBACKS
Default: []
List of data update callbacks to be called when data is updated. For example:
[
{
"url": "http://example.com/callback",
"key": "example", // optional
"config": { // optional
"headers": {
"Authorization": "Bearer token"
},
"method": "GET",
"data": {
"key": "value"
}
}
}
]
The default config is: {"method": "POST"}.
For more information, see the CallbackEntry interface.
Data update callbacks can increase data synchronization latency. Optimize the callback endpoint to handle expected loads efficiently.
PDP_FACTDB_ENABLED
Default: False
Enable FactDB for this PDP. For more information, see the FactDB documentation.
PDP_CACHE_STORE
Default: none
The cache storage type. Options include: none, in-memory, and redis. For more information, see the PDP Cache documentation.
Added in PDP v0.9.0
PDP_CACHE_TTL
Default: 3600
Time-to-live in seconds for cached items.
Added in PDP v0.9.0
PDP_CACHE_MEMORY_CAPACITY
Default: 128
Memory capacity in MiB for in-memory cache (when using in-memory store).
Added in PDP v0.9.0
PDP_CACHE_REDIS_URL
Default: "" (empty string)
Redis connection URL (when using redis store).
Added in PDP v0.9.0
PDP_HORIZON_PORT
Default: 7001
The port for the Horizon service. Horizon is the PDP's internal Python service bridge that facilitates communication between different components within the PDP.
Added in PDP v0.9.0
use UVICORN_PORT for PDP versions prior to v0.9.0
PDP_HORIZON_CLIENT_TIMEOUT
Default: 60
Timeout in seconds for Horizon client requests.
Added in PDP v0.9.0
PDP_HORIZON_NICENESS
Default: 10
The niceness value for the PDP Horizon process (the internal Python service). Niceness values range from -20 (highest priority) to 19 (lowest priority), where 0 represents equal priority.
This setting helps manage CPU resource allocation, particularly the interaction between the Horizon service and the OPA process. A higher value (e.g., 10, the default) makes Horizon 'nicer', yielding CPU more readily to other processes like OPA.
Added in PDP v0.9.0
PDP_HORIZON_HEALTH_CHECK_TIMEOUT
Default: 1
Timeout in seconds for individual health check requests to the Horizon service. If a health check takes longer than this timeout, it will be considered failed.
Added in PDP v0.9.0
PDP_HORIZON_HEALTH_CHECK_INTERVAL
Default: 5
Interval in seconds between consecutive health checks of the Horizon service. The PDP will continuously monitor the Horizon service at this interval.
Added in PDP v0.9.0
PDP_HORIZON_HEALTH_CHECK_FAILURE_THRESHOLD
Default: 12
Number of consecutive health check failures before the PDP will attempt to restart the Horizon service. This helps ensure service reliability by automatically recovering from failures.
Added in PDP v0.9.0
PDP_HORIZON_STARTUP_DELAY
Default: 5
Initial delay in seconds before the PDP begins health checking the Horizon service after startup. This allows the Horizon service time to fully initialize before monitoring begins.
Added in PDP v0.9.0
PDP_HORIZON_RESTART_INTERVAL
Default: 1
Interval in seconds between service restart attempts when the Horizon service needs to be restarted due to health check failures.
Added in PDP v0.9.0
PDP_HORIZON_TERMINATION_TIMEOUT
Default: 30
Timeout in seconds to wait for the Horizon service to gracefully terminate during shutdown or restart operations. After this timeout, the service will be forcefully terminated.
Added in PDP v0.9.0
PDP_OPA_URL
Default: http://localhost:8181
URL for the Open Policy Agent service.
Added in PDP v0.9.0
OPAL Configurations
The list below includes only the configurations that are most commonly used. Additional configurations are available in the OPAL documentation.
OPAL_SERVER_URL
Default: https://opal-v2.permit.io
The URL of the OPAL server.
This configuration is controlled by Permit.io, changing it can cause your PDP to malfunction.
OPAL_SERVER_WS_URL
Default: wss://opal-v2.permit.io
The WebSocket URL of the OPAL server.
This configuration is controlled by Permit.io, changing it can cause your PDP to malfunction.
OPAL_CLIENT_TOKEN
Default: automatically configured
The client token used to authenticate the PDP against the OPAL server.
This configuration is controlled by Permit.io, changing it can cause your PDP to malfunction.
OPAL_INLINE_OPA_ENABLED
Default: True
When enabled, run OPA inside the PDP server.
This configuration is controlled by Permit.io, changing it can cause your PDP to malfunction.
OPAL_INLINE_OPA_LOG_FORMAT
Default: none
The log format for OPA logs.
none- no logsminimal- only the event name is loggedhttp- log HTTP method, path, and status codefull- log the entire data returned
OPAL_INLINE_CEDAR_ENABLED
Default: True
When enabled, run Cedar inside the PDP server.
This configuration is controlled by Permit.io, changing it can cause your PDP to malfunction.
OPAL_INLINE_CEDAR_LOG_FORMAT
Default: none
The log format for Cedar logs.
none- no logsminimal- only the event name is loggedhttp- log HTTP method, path, and status codefull- log the entire data returned
OPAL_FETCHING_WORKER_COUNT
Default: 6
The number of workers to use for fetching data concurrently.
OPAL_FETCHING_CALLBACK_TIMEOUT
Default: 60
The timeout for fetching the callback, in seconds.
OPAL_FETCHING_ENQUEUE_TIMEOUT
Default: 10
The timeout for queueing a fetch, in seconds.
OPAL_ENABLE_DATADOG_APM
Default: False
Enables Datadog APM tracing.
Additional configurations are available in the OPAL documentation.
OPAL_LOG_DIAGNOSE
Default: False
Include diagnosis in log messages.
When OPAL_LOG_DIAGNOSE is set to True, it may print sensitive information, including secrets.
Additional configurations are available in the OPAL documentation.
OPAL_LOG_SERIALIZE
Default: False
Serialize log records as JSON format to STDERR (useful for log aggregation services)
Additional configurations are available in the OPAL documentation.
Additional Configurations
ALL_PROXY
When running the PDP behind an HTTP proxy in an isolated network, configure the proxy environment variables:
# Proxy for all protocols (i.e. HTTPS, WSS)
ALL_PROXY=http://proxy.example.com:8080
Configuring proxy via TLS / HTTPS is not supported. The PDP uses TLS connections for both HTTP and WebSocket protocols connecting to the control plane at Permit.io Cloud. At the moment, TLS in TLS is not supported, therefore requiring proxy to be accessible via HTTP only. For more information, see aiohttp documentation.
Your proxy must support HTTP/2 and WebSocket connections for the PDP to function properly. For detailed proxy setup instructions, see the OPAL proxy tutorial.
Added in PDP v0.9.4
UVICORN_NUM_WORKERS
Default: 1
The number of parallel workers to run the PDP server on.
GUNICORN_TIMEOUT
Default: 600
Maximum idle / unresponsive time before a worker is killed, in seconds. For more information, see the Gunicorn documentation.