Authorizing requests
Your application enforces authorization by asking the Policy Decision Point one question per sensitive operation: may this principal perform this action on this resource?
Prerequisites
Section titled “Prerequisites”- A project with a schema, at least one active policy, and entities (Quickstart).
- The project attached to a shared PDP, and its client token (Console → PDP).
Using TypeScript? The SDK wraps this API in a typed client — client.authorize(principal, action, resource) — with timeouts and retries built in. The HTTP contract below applies either way.
The request
Section titled “The request”curl -X POST https://<your-pdp-host>/authorize \ -H "Content-Type: application/json" \ -H "X-Client-Token: <client-token>" \ -H "Authorization: Bearer <end-user-jwt>" \ -d '{ "principal": "App::User::\"alice\"", "action": "App::Action::\"read\"", "resource": "App::Document::\"doc123\"", "context": { "mfa_verified": true } }'X-Client-Tokenroutes the request to your project’s policies and data. Keep it server-side; rotate it from the Console if it leaks.Authorizationoptionally carries the end user’s identity token. See Validating caller identity for when the PDP checks it.principal,action,resourceare Cedar entity references from your schema.contextis optional: arbitrary request-time data your policies can reference inwhenclauses (IP addresses, MFA state, time, amounts…). Cedar JSON extensions (__entity,__extn) are supported.
You cannot pass principal data (attributes, group memberships) in the request. Principals come only from the platform’s entity store, so a caller can never grant itself access by shaping its own request. By default a non-empty entities field is rejected with 400. The one exception is described next.
Inline resource entities
Section titled “Inline resource entities”Sometimes the resource being checked doesn’t exist in the entity store yet, for example a document created a moment ago, or an item read live from another system. For these cases you can attach the resource inline:
curl -X POST https://<your-pdp-host>/authorize \ -H "Content-Type: application/json" \ -H "X-Client-Token: <client-token>" \ -H "X-App-Token: <app-token-with-inline_entities-grant>" \ -d '{ "principal": "App::User::\"alice\"", "action": "App::Action::\"read\"", "resource": "App::Document::\"new-doc\"", "entities": [ { "uid": { "type": "App::Document", "id": "new-doc" }, "attrs": { "owner": "alice" }, "parents": [ { "type": "App::Folder", "id": "design-docs" } ] } ] }'- The
X-App-Tokenmust be an app token for the project with theinline_entitiespermission (actionassert). Without it, any non-emptyentitiesfield is rejected. - The slice may contain only the request’s resource and its ancestors (reachable through the slice’s own
parents), at most 16 entities. A principal, sibling, or any other entity is rejected with400. - Inline entities are validated against the project schema and override synced copies of the same UID for that request only. Nothing is written to the entity store.
- The inline slice is recorded on the request’s audit event.
The response
Section titled “The response”{ "code": 200, "description": "Authorization request processed successfully.", "data": { "decision": "Allow", "diagnostics": { "reason": ["policy_a1b2c3"], "errors": [] } }}decision—AlloworDeny. Enforce it directly: allow the operation or return your application’s 403.diagnostics.reason— the policy IDs that determined the decision; the same IDs appear in the Console and in audit events, so a support question (“why was I denied?”) is answerable from the audit log.diagnostics.errors— per-policy evaluation errors, if any.
A Deny with empty reason and errors means no permit policy matched — Cedar’s default.
Handling failures
Section titled “Handling failures”Treat anything other than a 200 with decision: Allow as a denial. The PDP is built the same way — every error path returns decision: Deny:
| Status | Meaning |
|---|---|
200 |
Decision evaluated: Allow or Deny. |
400 |
Malformed request (e.g. unparseable context, a malformed entity UID, or a rejected inline entities slice). |
401 |
Missing/unknown client token, failed identity-token validation (when active), or project data not yet loaded. |
403 |
The body principal does not match the authenticated identity (only when identity validation is active). |
500 |
Evaluation error (e.g. request doesn’t conform to the schema). |
Checking many actions at once
Section titled “Checking many actions at once”To decide which buttons or menu items to show, use POST /permissions instead of one /authorize call per action. It returns { "decisions": { "read": true, "share": false, … } } for a principal and resource in a single call. It records no audit events, so still call /authorize when the user actually performs the action.
Validating caller identity
Section titled “Validating caller identity”Without identity validation, the PDP trusts the principal your backend sends. That is appropriate when the PDP is only reachable from your own services and they resolve the user themselves.
Once identity validation is active, the PDP:
- validates each request’s bearer token — signature, issuer, audience, expiry;
- derives the authenticated principal from the token’s claims;
- rejects requests whose body
principaldisagrees with the token (403) — a service can’t ask on behalf of someone it isn’t.
If validation is enabled but signing keys can’t be loaded, the PDP fails closed rather than skipping the check.
Latency and availability
Section titled “Latency and availability”- Decisions are in-memory Cedar evaluations — typically sub-millisecond inside the PDP; your observed latency is network transit.
- The PDP serves last-known-good data through control-plane outages and restarts. Policy and entity changes propagate within one sync cycle (~20 seconds); attach/detach and token rotation propagate immediately.
- Wire
GET /healthinto your infrastructure checks: it returns200when the PDP is serving and503while starting.