How Permit.io Works

Learn how Permit.io makes authorization decisions: where your policy lives, where decisions run, and how policy changes reach your application. This page is for developers and architects who want to understand the architecture before they integrate Permit.

Authorization requirements grow from an admin or non-admin check into roles, attributes, and relationships. When that logic is spread through your code, every change needs a code release and is hard to keep consistent. Permit separates policy from code.

Decoupling policy and code

How a permission decision is made

1. IdentityA user, service, or AI agent, authenticated by your identity provider.
2. RequestYour code asks: can this identity perform this action on this resource?
3. Policy decision pointRuns in your VPC next to your services and evaluates policy with OPA or Cedar.
4. DecisionAllow or deny, returned to your code. The decision log records why.
5. AuditEvery decision is logged and can be forwarded to your logging stack or SIEM.

The same five steps apply whether the caller is a person clicking a button or an agent calling a tool. Only the identity changes.

When you decouple policy and code, your application code asks an authorization microservice for each decision, and the policy lives in that microservice instead of in your code. Open-source policy engines such as Open Policy Agent (OPA) and AWS Cedar can evaluate the policy in that microservice. Running a policy engine yourself takes ongoing work: connecting it to your application, to its policy sources, and to the data it needs, and building the access control interfaces on top.

Permit builds on these open-source projects and provides:

• An authorization microservice based on your policy engine of choice
• Open Policy Administration Layer (OPAL), which keeps the policy engine up to date with the latest policy and data
• SDKs for your language
• A cloud service, the control plane, where you manage policy in the dashboard or the API

Permit's hybrid architecture: control plane and data plane

The Permit architecture has two parts, a control plane and a data plane:

• The control plane is where you manage your authorization layer, in the UI or the API. It runs in Permit's cloud and holds your policy and the identifiers it refers to (user keys, roles, attributes).

• The data plane is where decisions are made. Policy decision points (PDPs), the services that evaluate policy, run in your own VPC or network, next to your services, and can use the data your policies need (names, emails, and other attributes) without sending it to Permit.

Hybrid deployment

Permit control plane

Permit cloud

• Policy editor and API
• Policy as code in your Git repo
• Audit logs

OPAL syncs policy and data

Your networkVPC, data center, or on-prem

Policy decision points

Run beside your services and answer checks locally, without a round trip to the control plane.

• Your apps and APIs
• Your data

Policy is managed in the control plane and evaluated in your network. The data your policies need can stay on your side.

With this split, you manage authorization in Permit, and the data your policies evaluate can stay in your network:

• Sensitive data can stay in your network, which helps with security and compliance requirements.

• Authorization decisions are made on your side, without a network round trip to Permit. When you run the PDP as a sidecar, checks go over the loopback interface, so there is no network latency.

• The PDP in your network answers checks, so decisions don't depend on a request to Permit's cloud.

Two components make the hybrid architecture work, OPAL and the Permit PDP:

OPAL: policy and data sync

Open Policy Administration Layer (OPAL) is an open-source project that the Permit.io team develops and maintains. OPAL is an administration layer for policy engines: OPAL detects changes to policy and policy data in real time and pushes live updates to the policy engines in your PDPs.

OPAL has two parts, the OPAL Server and the OPAL Client.

The OPAL Server runs in Permit's cloud service. The OPAL Server creates a pub/sub channel that OPAL clients subscribe to, tracks a Git repository (by webhook or polling) for policy updates, and pushes those updates to clients as diffs, so only changes are sent.

The OPAL Client runs inside each PDP and applies those updates to the policy engine.

The policy decision point (PDP)

A policy decision point (PDP) is a network node that answers authorization queries using policies and contextual data. The Permit PDP is your authorization microservice, and you deploy it beside your own services.

The Permit PDP has two parts, a policy engine and the OPAL Client:

• The policy engine evaluates authorization queries, using the policy rules as the source of truth. Policies are written in a policy language (such as Rego or Cedar), and the engine interprets them to return a decision for each query.

  Permit is policy engine agnostic and supports Open Policy Agent and AWS Cedar, so you can choose the engine for your policies.

• The OPAL Client runs alongside the policy engine and keeps it up to date with the latest policy and data. It subscribes to topic-based pub/sub updates for both data and policy, and fetches them from the OPAL Server (in Permit's cloud service) and from any other relevant sources (for example databases, APIs, and third-party services).

Together, Permit's cloud service, OPAL, and the PDP let you change your authorization layer in Permit (in the UI or the API). OPAL pushes those changes to your PDPs, and the data your policies evaluate stays in your network.

Next steps

• Run the PDP
• Read the PDP documentation
• Compare the control plane and data plane
• Choose a policy engine