Skip to content

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?

  • 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.

Terminal window
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-Token routes the request to your project’s policies and data. Keep it server-side; rotate it from the Console if it leaks.
  • Authorization optionally carries the end user’s identity token. See Validating caller identity for when the PDP checks it.
  • principal, action, resource are Cedar entity references from your schema.
  • context is optional: arbitrary request-time data your policies can reference in when clauses (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.

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:

Terminal window
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-Token must be an app token for the project with the inline_entities permission (action assert). Without it, any non-empty entities field 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 with 400.
  • 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.
{
"code": 200,
"description": "Authorization request processed successfully.",
"data": {
"decision": "Allow",
"diagnostics": {
"reason": ["policy_a1b2c3"],
"errors": []
}
}
}
  • decision — Allow or Deny. 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.

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).

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.

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:

  1. validates each request’s bearer token — signature, issuer, audience, expiry;
  2. derives the authenticated principal from the token’s claims;
  3. rejects requests whose body principal disagrees 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.

  • 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 /health into your infrastructure checks: it returns 200 when the PDP is serving and 503 while starting.