Skip to main content

Nexus PDP configuration reference

This reference lists the environment variables that configure Permit Nexus PDP (permitio/nexus-pdp), a self-hosted policy decision point (PDP). It is for operators who deploy and tune Nexus PDP. The only required setting is a key: PDP_API_KEY, or a project or organization API key with the environment to serve. For deployment requirements such as volumes, probes, and memory, see Deploy Nexus PDP.

Nexus PDP configuration can change between early-access releases

As of September 2026, Nexus PDP is in early access. Permit can rename, replace, or remove the variables and defaults on this page before general availability. Pin the Nexus PDP image as described in Image name and tags, not to a moving tag such as 0-beta, and check this page when you upgrade. If you depend on a specific variable, tell Permit support at support@permit.io.

The container PDP (the Edge PDP image permitio/pdp-v2) uses a different set of variables. See the container PDP configuration reference. A variable with the same name can mean something different on each PDP type.

Credentials​

VariableDefaultDescription
PDP_API_KEYRequired, unless a project or organization key is setThe Nexus PDP API key of the Permit environment this Nexus PDP serves, from the Permit dashboard. As of November 2026, the dashboard labels this action Copy Nexus PDP API Key. The ordinary environment API key does not work.
PDP_PROJECT_API_KEYNoneA project API key. Use it with PDP_ACTIVE_ENV instead of PDP_API_KEY.
PDP_ORG_API_KEYNoneAn organization API key. Use it with PDP_ACTIVE_PROJECT and PDP_ACTIVE_ENV instead of PDP_API_KEY.
PDP_ACTIVE_PROJECTNoneThe ID or key of the project, with PDP_ORG_API_KEY. Ignored with PDP_PROJECT_API_KEY.
PDP_ACTIVE_ENVNoneThe ID or key of the environment this Nexus PDP serves, with PDP_PROJECT_API_KEY or PDP_ORG_API_KEY.
PDP_BACKEND_URLhttps://api.permit.ioThe Permit API that Nexus PDP asks for the environment's Nexus PDP API key when it starts with a project or organization key. It must use https, except for localhost and loopback addresses.

Start with a project or organization API key​

Instead of the environment's Nexus PDP API key, you can give Nexus PDP a project or organization API key and name the environment to serve, as with the container PDP. When it starts, Nexus PDP uses that key to get the environment's Nexus PDP API key from the Permit API, and from then on runs exactly as if you had set PDP_API_KEY.

  • With PDP_PROJECT_API_KEY, set PDP_ACTIVE_ENV. The project is the API key's own project. If you also set PDP_ACTIVE_PROJECT, Nexus PDP ignores it and logs a warning.
  • With PDP_ORG_API_KEY, set PDP_ACTIVE_PROJECT and PDP_ACTIVE_ENV.
  • If PDP_API_KEY is also set, PDP_API_KEY wins and Nexus PDP logs a warning. If both a project and an organization key are set, the project key wins.
  • The API key needs write access to the environment. A read-only key is refused.
  • Nexus PDP serves one environment. To serve another, start another Nexus PDP.

If Nexus PDP cannot get the key, it stops at startup with one of these errors:

ErrorWhat to check
The key is invalid or revokedThe project or organization API key in PDP_PROJECT_API_KEY or PDP_ORG_API_KEY.
The key is an environment keySet an environment's Nexus PDP API key as PDP_API_KEY instead.
The key has no access to the environmentThe environment must be in the key's project (or organization), and the key needs write access.
No such project or environmentPDP_ACTIVE_PROJECT and PDP_ACTIVE_ENV.
The environment has no Nexus PDPEnable Nexus PDP for the environment in the Permit dashboard first.

If the Permit API is unreachable or busy, Nexus PDP retries for up to two minutes, then stops so that your orchestrator restarts it.

PDP_API_KEY is the only credential Nexus PDP needs when you set it. The PDP_API_KEY value:

  • binds the container to exactly one Permit environment,
  • authenticates the container to Permit's control plane,
  • carries the address of the control plane, so Nexus PDP connects without a separate URL setting,
  • is the bearer token that the Nexus PDP authorization API accepts from your services,
  • is accepted by the Permit API with the same access as the environment API key, so protect it the same way.
No control-plane URL to set on Nexus PDP

Leave PDP_CONTROL_PLANE unset unless Permit support asks you to set it. On the container PDP, PDP_CONTROL_PLANE is the Permit API URL. On Nexus PDP, PDP_CONTROL_PLANE overrides the control-plane address that PDP_API_KEY carries. The Permit API URL that Nexus PDP calls with a project or organization key is PDP_BACKEND_URL.

Storage and ports​

VariableDefaultDescription
EDGE_DB_PATH/var/lib/edge-pdp/dbDirectory of the embedded database. Must be on a persistent volume.
EDGE_DATA_DIR/var/lib/edge-pdpDirectory of the event store and generated credentials. Must be on a persistent volume.
EDGE_PUBLIC_PORT7000Port of the authorization API, the only port your services call.
EDGE_HEALTH_PORT7001Port of the health and readiness endpoints. Point probes at this port, not at the authorization port.

Both storage paths must be on persistent storage that survives restarts. On ephemeral storage, every restart runs a full cold start. See Nexus PDP deployment requirements.

Nexus PDP also uses ports 7002, 7003, 8181, 4222, and 8222 internally, bound to loopback only. See Ports used by Nexus PDP. Expose only the ports set by EDGE_PUBLIC_PORT and EDGE_HEALTH_PORT.

Behavior and tuning​

VariableDefaultDescription
RUST_LOGinfoLog level of Nexus PDP. Set info,edge_pdp=debug to add Nexus PDP debug logs.
PDP_DEBUGUnset (off)Set to true to add debug information to policy evaluation requests.
OPA_TIMEOUT_MS2000Timeout for each policy evaluation request to Open Policy Agent (OPA), in milliseconds: the deadline of a whole decision (except the list endpoints, /user-permissions, /user-tenants, /authorized_users and the AuthZEN searches, which run on their own longer deadline set by PDP_ABAC_LIST_TIMEOUT_MS). Keep it above QUERY_DEFAULT_TIMEOUT_MS, which Nexus PDP warns about at startup when it is not, and below your client's own timeout.
QUERY_DEFAULT_TIMEOUT_MS1000Time limit for each data query OPA makes during a decision, in milliseconds. A query that runs past it fails, and the check is denied: Nexus PDP returns its normal deny answer, and only a Failed to query warning in the Nexus PDP log tells it apart from a real deny.
EDGE_PARALLELISM4Number of change transactions Nexus PDP applies concurrently.
EDGE_DECISION_LOG_OPT_OUTfalseSet to true to stop sending decision logs to Permit.
EDGE_DRAIN_TIMEOUT_SECS10Seconds that in-flight requests have to finish during shutdown before Nexus PDP aborts them.
EDGE_CHILD_TERMINATION_TIMEOUT_SECS30Seconds that OPA and the NATS leaf node have to stop after SIGTERM before Nexus PDP sends SIGKILL.

Set the Kubernetes terminationGracePeriodSeconds to at least EDGE_DRAIN_TIMEOUT_SECS plus EDGE_CHILD_TERMINATION_TIMEOUT_SECS, which is 40 seconds at the defaults. See Nexus PDP deployment requirements.

Child process logging​

VariableDefaultDescription
EDGE_NATS_LOG_LEVELFollows RUST_LOGLog level of the NATS leaf node that connects to the control plane: info, debug, or trace.
EDGE_OPA_LOG_LEVELFollows RUST_LOGLog level of OPA: debug, info, or error.
Child process debug levels write authorization data to logs

EDGE_NATS_LOG_LEVEL=trace logs raw message payloads, which contain your authorization data. EDGE_OPA_LOG_LEVEL=debug logs authorization request and response bodies. Set these levels only for short debugging sessions, and remove them before the container serves production traffic.

Storage engine​

The Nexus PDP embedded database (SurrealDB on RocksDB) uses storage-engine defaults sized for large workloads, not for a small container. These variables have the largest effect on memory use:

VariableDefaultEffect
SURREAL_ROCKSDB_BLOCK_CACHE_SIZE536870912 (512 MiB)Size of the read cache. The largest contributor to resident memory.
SURREAL_ROCKSDB_WRITE_BUFFER_SIZE268435456 (256 MiB)Size of each in-memory write buffer before RocksDB flushes it to disk.
SURREAL_ROCKSDB_MAX_WRITE_BUFFER_NUMBER32Maximum number of write buffers in memory at once.
SURREAL_ROCKSDB_BACKGROUND_THREADS4Number of background compaction threads.

At these defaults, a container with a memory limit of a few hundred MiB is killed for running out of memory (OOM) at startup. Start with 4 GiB of memory, then lower these values while you load test against your own data set. See Nexus PDP resource footprint.

Contents

Edit this page

Need help?