Skip to content

Policy Decision Point

The Policy Decision Point (PDP) is the engine that answers authorization requests. It holds your project’s policies, schema, and entities in memory — compiled and ready to evaluate — so a decision is an in-memory Cedar evaluation, not a round-trip to the control plane.

From the Console, attach your project to a shared regional PDP: pick a region, and the platform registers your project with that region’s decision point and issues a client token. The PDP syncs your project’s policies, schema, and entities immediately, and your applications can start calling its HTTP API. The client token can be rotated from the Console at any time, and detaching the project evicts its data from the PDP.

POST /authorize

{
"principal": "App::User::\"alice\"",
"action": "App::Action::\"read\"",
"resource": "App::Document::\"doc123\"",
"context": {}
}

Headers that accompany the request:

  • X-Client-Token (required): your project’s client token, issued when you attach the project to a PDP (rotatable from the Console). It routes the request to your project’s policies and data.
  • Authorization: Bearer <jwt> (optional): the end user’s identity token. See trusted identity providers for when it is validated.
  • X-App-Token (optional): only when sending inline resource entities.

The response:

{
"code": 200,
"data": {
"decision": "Allow",
"diagnostics": {
"reason": ["policy_id_1"],
"errors": []
}
}
}
  • decision is Allow or Deny. Cedar is deny-by-default: if no permit policy matches, the answer is Deny.
  • diagnostics.reason lists the policy IDs that determined the decision — the same IDs you see in the Console and in audit events.
  • Error responses always carry decision: Deny; a failure can never widen access.

Principals, their attributes, and their group memberships come exclusively from the entity store synced from the control plane. A caller can never grant itself membership or attributes by shaping its own request.

By default the request accepts no entity data at all: a non-empty entities field is rejected with 400. The only exception is inline resource entities. With an app token that holds the inline_entities grant, a caller may attach the request’s resource and its ancestors (at most 16 entities). They are schema-validated and override the synced copies for that one request.

POST /permissions answers “what can this principal do to this resource?” in one call. It’s useful for showing or hiding buttons in your UI without one /authorize call per action.

{
"principal": "App::User::\"alice\"",
"resource": "App::Document::\"doc123\"",
"context": {},
"actions": ["read", "update", "share"]
}

It uses the same headers as /authorize (X-Client-Token, optional end-user Authorization). The response maps each action to true or false:

{
"code": 200,
"data": {
"decisions": { "read": true, "share": false, "update": true },
"errors": []
}
}
  • Actions are short action IDs ("read", not App::Action::"read"). Without actions, every action your schema allows for that principal and resource type is evaluated. A requested action the schema doesn’t allow for that pair comes back false.
  • Evaluation is deny-by-default: an action that errors is reported as false.
  • It does not accept inline entities, and it emits no audit events. Use it to shape your UI, and keep /authorize on the path that actually performs the operation.

In the Console you can register the OIDC identity providers your applications use for each project. A provider is defined by its issuer, JWKS URL, optional audience, the header and prefix the token arrives in, and the claim that maps to the Cedar principal and its entity type.

When provider validation is active, the PDP checks each request’s bearer token (signature, issuer, audience, expiry). It also rejects requests whose body principal does not match the authenticated identity, which blocks confused-deputy requests. If validation is enabled but signing keys cannot be loaded, the PDP fails closed.

The PDP pulls everything from the control plane; it is a cache, never a source of truth.

  • Policies and schema are refreshed continuously (roughly every 20 seconds).
  • Entities sync incrementally from a change feed, so updates — including deletions — reach the PDP within one sync cycle. A full resync runs every 24 hours as a safety net.
  • New projects registered to a PDP are synced immediately, not on the next cycle.

The PDP is built to keep answering correctly even when the control plane is unreachable:

  • After every successful sync it writes a snapshot to disk. On restart it serves from the snapshot immediately, even if the control plane is down.
  • If a refresh fails, the PDP keeps serving its last-known-good data rather than denying everything.
  • A policy set that fails to compile is rejected wholesale — the PDP will never install a partial policy set that might silently drop a forbid rule.

GET /health returns 200 once the PDP has loaded its project data, and 503 while it is still starting — safe to wire directly into load-balancer health checks.

Every decision is queued as an audit event, batched, spooled durably to disk, and delivered to the audit service with at-least-once semantics. A PDP restart or deploy does not lose decision records.