Run Local Authorization Microservice
Configure the policy decision point (PDP) container that runs next to your application, then check its health, metrics, and API documentation. This page is for developers who run the PDP as a local authorization microservice instead of using the managed Cloud PDP.
Why run the PDP locally
A local PDP evaluates permission checks inside your infrastructure instead of in Permit's cloud. The control plane in Permit's cloud still stores your policy, and Open Policy Administration Layer (OPAL) pushes policy and data changes to the PDP.
Performance
The PDP evaluates every decision next to your application, so checks don't make a network round trip to Permit. When you run the PDP as a sidecar on the same host, the check goes over the loopback interface, so there is no network latency.
A well-configured local PDP answers thousands of checks per second with sub-millisecond latency, and under 10ms at p95 end to end from your application. Some customers serve millions of decisions a day from a single PDP instance. Your figures depend on policy complexity, the amount of data the PDP holds, and the host it runs on.
Security and data residency
The data your policies evaluate can stay in your infrastructure, which helps you meet data residency requirements. You control where the PDP runs and who can reach it.
Reliability
The PDP in your network answers the checks, so decisions don't depend on a request to Permit's cloud. You run and scale the PDP like any other service in your infrastructure.
Full policy model support
A local PDP supports every policy model: role-based access control (RBAC), attribute-based access control (ABAC), and relationship-based access control (ReBAC). The Cloud PDP does not support ABAC. See Cloud PDP capabilities.
Prerequisites
- Your environment API key. See Get your API key.
- Docker. See Install Docker.
Start the PDP container
Pull and run the permitio/pdp-v2 image with the steps in Run the PDP. The container PDP listens on port 7000 inside the container. The docker run commands on this page map that port to localhost:7766 on your machine, so your application and the SDK send checks to http://localhost:7766.
To find the container ID and read the PDP output, run:
docker ps
docker logs <container_id>
Each docker run command below replaces the basic command from Run the PDP. Stop the running container first (docker stop <container_id>), or port 7766 is already in use and Docker fails to start the second container.
Configure the PDP container
The PDP reads its configuration from environment variables that you pass with --env. This section covers the most common options. For every variable, see PDP configuration.
Print decisions to the console
Add PDP_OPA_DECISION_LOG_CONSOLE to print every authorization decision to the container output, and PDP_DEBUG for debug-level logs:
docker run -it -p 7766:7000 \
--env PDP_DEBUG=True \
--env PDP_API_KEY=<YOUR_API_KEY> \
--env PDP_OPA_DECISION_LOG_CONSOLE=True \
permitio/pdp-v2:latest
| Variable | Default | Effect |
|---|---|---|
PDP_DEBUG | not set | Adds debug detail to the logs, including how the PDP evaluates policies. |
PDP_OPA_DECISION_LOG_CONSOLE | False | Prints each decision and its result to the console. Applies only while PDP_OPA_DECISION_LOG_ENABLED is True. |
Expose the OPA port
The PDP container runs Open Policy Agent (OPA), the policy engine, on port 8181. Add a second port mapping to reach the OPA API directly for policy queries and debugging:
docker run -it -p 7766:7000 -p 8181:8181 \
--env PDP_API_KEY=<YOUR_API_KEY> \
permitio/pdp-v2:latest
| Host port | Container port | Serves |
|---|---|---|
7766 | 7000 | The PDP API. Your application and SDK send checks here. |
8181 | 8181 | The OPA API. |
The OPA API rejects requests without an Authorization: Bearer <YOUR_API_KEY> header, except for OPA's /health endpoint. Don't expose port 8181 outside your network.
Tune decision log uploads
The PDP uploads decision logs to Permit, where they appear in the Audit Log screen. Control the uploads with these variables:
docker run -it -p 7766:7000 \
--env PDP_API_KEY=<YOUR_API_KEY> \
--env PDP_OPA_DECISION_LOG_ENABLED=True \
--env PDP_OPA_DECISION_LOG_MIN_DELAY=1 \
permitio/pdp-v2:latest
| Variable | Default | Effect |
|---|---|---|
PDP_OPA_DECISION_LOG_ENABLED | True | Uploads decision logs to Permit. Set to False and the Audit Log screen shows no decisions from this PDP. |
PDP_OPA_DECISION_LOG_MIN_DELAY | 1 | Minimum number of seconds between uploads. |
PDP_OPA_DECISION_LOG_MAX_DELAY | 10 | Maximum number of seconds between uploads. |
Monitor the PDP
Check PDP health
The PDP serves a health endpoint on the PDP API port:
http://localhost:7766/health
A healthy PDP returns HTTP 200 with "status": "ok". If a component inside the PDP is not healthy, the endpoint returns HTTP 503 with "status": "error". The endpoint needs no API key, so you can use it for container liveness and readiness probes. The PDP also answers the same check at /ready and /healthy.
Collect PDP metrics
OPA inside the PDP serves Prometheus metrics at /metrics on port 8181:
http://localhost:8181/metrics
To read the metrics, map port 8181 as shown in Expose the OPA port. Send your API key as a bearer token, or set PDP_ALLOW_METRICS_UNAUTHENTICATED=True so your monitoring stack can scrape the endpoint without a token. For PDP connection status in the Permit dashboard, see Monitoring PDPs.
Browse the PDP API documentation
The PDP serves ReDoc documentation for its own API:
http://localhost:7766/redoc
The page lists every PDP endpoint with its request and response format. For a hosted copy, see the PDP API reference.