Skip to main content

Permit's PDP (Policy Decision Point)

A policy decision point (PDP) is a network node that answers authorization queries using policies and contextual data. Every permission check your application makes goes to a PDP, so PDPs need to be highly available and close to the services that query them.

The Permit PDP is your authorization microservice. It bundles OPA, the OPAL client, and an API server.

You run the PDP as a Docker container. Deployed next to your services, it answers checks locally, without a network round trip to Permit. As a sidecar on the same host, checks go over the loopback interface, so they carry no network latency and stay in the sub-millisecond range. Like all of Permit's customer-deployed components, the Permit PDP is open source and available from Docker Hub.

Use the PDP​

You can use the PDP for testing and enforcement in several ways:

PDP deployment types: Cloud, Edge, and Nexus​

When we talk about PDP deployment, we distinguish between:

  • Managed Cloud PDP – A fully managed, multi-tenant PDP hosted by Permit.io at https://cloudpdp.api.permit.io.
    Ideal for fast onboarding, low-ops production workloads, and standard RBAC/ReBAC authorization at scale.

  • Edge PDP (self-hosted PDP) – PDP containers you run as a sidecar, centralized service, or cluster inside your own VPC, Kubernetes cluster, or VMs.
    Ideal when you need tight latency within your own network, ABAC, custom data sources, read-your-own-writes, or PDP-level callbacks and healthchecks.

  • Nexus PDP – A self-hosted PDP (permitio/pdp-v3) with an embedded on-disk database, kept in sync over a durable event stream.
    Ideal for large data sets, relationship-heavy ReBAC, and decisions that never depend on reaching Permit.

Most teams start with the Managed Cloud PDP to get value quickly, and then introduce Edge PDPs for latency-sensitive or advanced scenarios.

Nexus PDP​

The Permit Nexus PDP is a ground-up rewrite of the PDP runtime. You run one container per Permit environment in your own network. It keeps a local, on-disk copy of that environment's policy and authorization data and answers checks with no network call in the decision path. Product overview

How it differs from the container PDP:

  • Data on disk, not in memory. The container PDP holds your data inside OPA's in-memory JSON document, so a large environment needs a large PDP. Nexus PDP stores the data in an embedded database on disk and keeps a bounded, configurable cache in memory.
  • Built for relationship queries. Relationship data lives in a store built for graph traversal, which OPA queries over loopback while it evaluates policy.
  • Sync that survives disconnection. Updates arrive already containing the change, and the control plane retains each PDP's unacknowledged changes until that PDP applies them. There is no re-fetch after a reconnect.
  • Availability over freshness. If the control plane is unreachable, the PDP keeps answering from its local copy and reports how stale it is.

What it supports today: RBAC, ReBAC with role derivation, and multi-tenancy, through the same check, bulk check, user permissions, authorized users, and AuthZen endpoints as the container PDP. Its capability envelope matches the managed Cloud PDP, deployed in your network. ABAC, policy as code, local facts, URL-based enforcement, and custom data sources are container PDP capabilities today.

When to choose it: use Nexus PDP for large data sets and relationship-heavy authorization that you want to run in your own network. Use the container PDP when you need ABAC, custom Rego, read-your-own-writes, or the other capabilities listed on the feature parity page. Both connect to the same Permit environment and enforce the same policies, so you can run them side by side.

Early access, with parity in progress

Nexus PDP is in early access and enabled per account; contact us to turn it on. Feature parity with the Classic PDP (the container PDP) is in progress and ships continually.

Read more: Architecture · How it works · Feature parity · Deployment · Configuration

Managed Cloud PDP​

Permit.io provides a managed, production-ready Cloud PDP at https://cloudpdp.api.permit.io which is available globally.

You can connect quickly with the Cloud PDP when first trying out Permit, and you can also continue using it in production for many workloads.

from permit import Permit

permit = Permit(
    token="[your-api-key]",
    pdp="https://cloudpdp.api.permit.io",
)
note

Cloud PDP supports RBAC and ReBAC policy models. ABAC is not supported on Cloud PDP.

For detailed capabilities and limits, see Cloud PDP Capabilities.

We recommend deploying an Edge PDP (self-hosted PDP) inside your network for ABAC policies, read-your-own-writes semantics, and specialized or latency-sensitive production deployments.

Run an Edge PDP With Docker​

You can run an Edge PDP on your local machine as a container on Docker Desktop. You will need this to use ABAC / advanced policies, custom data sources, and consistency features such as Send Consistent Updates (read-your-own-writes).

To run the PDP use the following command:

docker run -it \
  -p 7766:7000 \
  --env PDP_API_KEY=<your-permit-api-key> \
  --env PDP_DEBUG=True \
  permitio/pdp-v2:latest

In your application code, use the following PDP address in the Permit client to perform authorization queries.

from permit import Permit

permit = Permit(
    token="[your-api-key]",
    pdp="http://localhost:7766",
)

Production Deployment Models​

Permit.io supports all Edge PDP layouts and provides the missing layers on-top of open-source PDP solutions (such as OpenPolicyAgent).
These layouts describe self-hosted PDPs that you run inside your own infrastructure.
These layers include policy delivery and updating, supporting data collection, application level SDKs, application level instrumentation and more.

New to PDPs?

If you're new to Permit, follow this path:

Cloud PDP – when not to use it

The Managed Cloud PDP is production-ready for many RBAC/ReBAC workloads, but you should prefer an Edge PDP when you need:

  • ABAC policies or custom external data sources
  • Read-your-own-writes guarantees using Send Consistent Updates
  • PDP-level callbacks / health-based consistency hooks into your infrastructure
  • Hard latency SLOs strictly within your own VPC or on-prem network

For these cases, deploy an Edge PDP (self-hosted PDP) as a sidecar, centralized service, or cluster close to your applications.

info

Custom cloud PDP deployments are available to enterprise tier customers. Those can include different regions, cloud providers, custom SSL/TLS configurations or other specifications.

Please reach out to us at support@permit.io, or schedule a call via this link: https://calendly.com/permitio/

Hosted as an Edge PDP Sidecar​

The simplest way to integrate PDPs into a microservices architecture is as sidecars; meaning each microservice has a sidecar container next to it which it can query for policy.

For more information, see the sidecar deployment guide.

Centralized Edge PDP​

You can deploy a centralized PDP to handle authorization queries from multiple services.

This way is simple to set up and manage, but as the number of services grows, the PDP can become a bottleneck.

Cluster of Edge PDPs​

For high availability and scalability, you can deploy a cluster of PDPs behind a load balancer.

You can use our PDP Helm chart to create a Kubernetes deployment with multiple PDPs. For more information, see the Deploying using Helm guide.

Sharded Edge PDPs​

For truly massive data sets needed in the PDP, you can apply sharding to split the data between multiple PDPs within the same cluster.

PDP Caching Mechanism​

The PDP server includes a configurable caching mechanism that significantly improves performance by reducing redundant policy evaluations. When enabled, the cache stores results of policy decisions with a configurable time-to-live (TTL), providing performance benefits for frequently evaluated permissions.

You can configure the cache to use either an in-memory store for single instance deployments or Redis for distributed caching across multiple PDP instances.

For the /allowed/bulk endpoint, the cache is applied to each individual query within the bulk request. The cache is shared with the /allowed endpoint, meaning individual permission checks within a bulk request can benefit from previously cached results from single /allowed calls and vice versa.

Note that while caching significantly improves performance, it may lead to temporarily inaccurate results if permissions change during the cache TTL period.

Supported APIs:

  • ✅ /allowed
  • ✅ /allowed/bulk
  • ✅ /user-permissions
  • ✅ /authorized_users

For detailed configuration options, see the Cache Configuration section.

AuthZen Compatibility​

Permit's PDP is compatible with the OpenID AuthZen Authorization API 1.0 specification, providing a standardized way for Policy Enforcement Points (PEPs) to communicate with Policy Decision Points (PDPs). The AuthZen protocol enables interoperability between different authorization systems by defining a common API interface.

Access Evaluation​

Check if a subject can perform an action on a resource.

curl -X POST http://localhost:7766/v1/access/evaluation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subject": { "type": "user", "id": "alice@example.com" },
    "action": { "name": "read" },
    "resource": {
      "type": "document",
      "id": "doc123",
      "properties": { "tenant": "default", "is_public": true }
    },
  }'

Response: {"decision": true}

info

Notice that we pass the tenant property along with inline ABAC attributes via the properties field.

Bulk Access Evaluations​

Evaluate multiple access requests with top-level attributes.

curl -X POST http://localhost:7766/v1/access/evaluations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subject": {
      "type": "user",
      "id": "alice@example.com",
      "properties": { "department": "engineering" }
    },
    "evaluations": [
      {
        "action": {"name": "read"},
        "resource": {"type": "document", "id": "doc123", "properties": {"tenant": "default"}}
      },
      {
        "action": {"name": "write"},
        "resource": {"type": "document", "id": "doc456", "properties": {"tenant": "default"}}
      }
    ]
  }'

Response: {"evaluations": [{"decision": true}, {"decision": false}]}

Find subjects that can perform an action on a resource.

curl -X POST http://localhost:7766/v1/subjects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "action": {"name": "read"},
    "resource": {
      "type": "document",
      "id": "doc123",
      "properties": {"tenant": "default"}
    },
  }'

Response: {"subjects": [{"type": "user", "id": "alice@example.com"}]}

Find resources a subject can access for a given action.

curl -X POST http://localhost:7766/v1/resources \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subject": { "type": "user", "id": "alice@example.com" },
    "action": {"name": "read"},
  }'

Response: {"resources": [{"type": "document", "id": "doc123"}]}

Find actions a subject can perform on a resource.

curl -X POST http://localhost:7766/v1/actions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subject": {"type": "user", "id": "alice@example.com"},
    "resource": {
      "type": "document",
      "id": "doc123",
      "properties": {"tenant": "default"}
    },
  }'

Response: {"actions": [{"name": "read"}, {"name": "write"}]}

info

The AuthZen protocol is fully compatible with Permit's existing policy models. All policy changes made through the Permit dashboard or API are immediately available through the AuthZen endpoints.

Powered by OPA+OPAL​

Permit.io's PDP orchestration is powered by OPAL - an open source project - developed by the team at Permit.io and supported by a large community of developers and users. Check out this talk with the primary authors of OPAL to learn more about the unique realtime architecture:

OPAL's built-in separation of the data plane from the control plane, enables Permit.io users to enjoy the benefits of a fully distributed PDP solution, without having to be dependant on the availability of the Permit.io cloud, or sharing any data with it.

Contents

Edit this page

Need help?