---
title: "Test Cedar policy evaluation against real entities"
method: POST
path: "/zones/{zone_id}/policy-evaluations"
tags: ["PolicyEvaluations"]
---

# Test Cedar policy evaluation against real entities

`POST /zones/{zone_id}/policy-evaluations`

Stateless evaluation endpoint for testing Cedar policy evaluation against real entities before deployment. Supports evaluating a single policy, a full policy set, or raw Cedar text.

## Path parameters

- `zone_id` string, required

## Headers

- `X-API-Version` string
- `X-Client-Request-ID` string, uuid

## Request body

- PdpPolicyEvaluationRequest
  - `principal_type` 'user' | 'application', required
  - `principal_id` string, required — Public ID of the user or application.
  - `action` string, required — Cedar action to evaluate (e.g. `any`). The engine namespaces actions automatically as `Keycard::Action::"<name>"`.
  - `resource_id` string, required — Public ID of the resource.
  - `subject_type` 'user' | 'application'
  - `subject_id` string — Public ID of the subject (required when subject_type is set).
  - `context` PdpEvaluationContext — Additional context for Cedar authorization evaluation. Fields here are mapped directly into the Cedar `context` record.
    - `scopes` string[] — OAuth scopes associated with the request. Mapped to `context.scopes` in the Cedar evaluation as a `Set<String>`.
    - `session_id` string — Session identifier for the current authorization context. Mapped to `context.session_id` in Cedar.
    - `claims` PdpEvaluationClaims — Token claims for the actor and/or subject. Mapped to `context.actor_claims` and `context.subject_claims` in Cedar.
      - `actor` PdpClaimsData — Represents token claims passed into the Cedar context. Mapped to the Cedar `Keycard::Claims` type. Known fields (`email`, `groups`, `issuer_claims`) are typed; additional claims are passed through as untyped key-value pairs via `additionalProperties`.
        - `email` string — Email claim from the authentication token.
        - `groups` string[] — Group membership claims from the authentication token.
        - `issuer_claims` PdpIssuerClaims — Issuer-specific claims forwarded opaquely from STS (e.g. GHA OIDC assertion claims). Mapped to `context.actor_claims.issuer_claims` in Cedar. All fields are optional and issuer-dependent. See issuer documentation for available claim fields.
      - `subject` PdpClaimsData — Represents token claims passed into the Cedar context. Mapped to the Cedar `Keycard::Claims` type. Known fields (`email`, `groups`, `issuer_claims`) are typed; additional claims are passed through as untyped key-value pairs via `additionalProperties`.
        - `email` string — Email claim from the authentication token.
        - `groups` string[] — Group membership claims from the authentication token.
        - `issuer_claims` PdpIssuerClaims — Issuer-specific claims forwarded opaquely from STS (e.g. GHA OIDC assertion claims). Mapped to `context.actor_claims.issuer_claims` in Cedar. All fields are optional and issuer-dependent. See issuer documentation for available claim fields.
  - `policy_source` PdpPolicySource, required — Specifies which policies to evaluate. Exactly one of policy, policy_set, raw, or manifest must be provided.
    - `policy` PdpPolicyRef
      - `policy_id` string, required — Public ID of the policy.
      - `version_id` string — Public ID of a specific policy version. When omitted, the draft is used. If no draft exists, returns 400.
      - `schema_version` string — Cedar schema version override (date string, e.g. "2026-03-16"). When omitted, uses the schema_version recorded on the resolved policy version or draft.
    - `policy_set` PdpPolicySetRef
      - `policy_set_id` string, required — Public ID of the policy set.
      - `version_id` string — Public ID of a specific policy set version. When omitted, the draft is used. If no draft exists, returns 400.
    - `raw` PdpRawPolicyInput
      - `cedar` string, required — Raw Cedar policy text. Can contain one or more policy statements. Converted to JSON before evaluation.
      - `schema_version` string, required — Cedar schema version to evaluate against.
      - `validate` boolean — When true, validate the converted policy against the schema before evaluation. Validation errors are returned as 400 with details. Set to false to skip validation and attempt evaluation directly.
    - `manifest` PdpInlinePolicySetManifest — Inline policy-set manifest used by the `manifest` variant of PolicySource. Mirrors the shape of a stored policy set version's manifest so a policy set under construction (no stored id/version) can be tested without being saved first. The `sha` field on each entry is ignored on input and recomputed server-side.
      - `entries` PdpPolicySetManifestEntry[], required
        - `policy_id` string, required
        - `policy_version_id` string, required
        - `sha` string — SHA-256 of the policy version content, populated by the server
      - `schema_version` string, required — Cedar schema version the entries are validated against.

## Response `200`

The evaluation result

- PdpPolicyEvaluationResponse
  - `decision` 'allow' | 'deny', required
  - `evaluation_status` 'complete' | 'partial'
  - `determining_policies` string[] — Raw Cedar policy IDs that determined the decision, of the form "<policy_version_id>::<cedar_key>", unioned across sub-checks. See `checks` for the resolved, human-readable form with per-check attribution.
  - `checks` PdpEvaluationCheck[] — Per-sub-check results, each with the policies that determined it. A simple request has one actor check; an on-behalf-of / impersonation request has a subject check and an actor check. The overall decision is deny-wins across these. Determining-policy names and policy-set version populate only when evaluating a minted policy set/version; raw text and drafts are structural.
    - `role` 'actor' | 'subject' — actor = the requesting principal's access (or its right to act for the subject in an on-behalf-of flow); subject = the impersonated / delegated principal's own access.
    - `decision` 'allow' | 'deny'
    - `determining_policies` PdpDeterminingPolicyDetail[]
      - `policy_id` string
      - `policy_name` string
      - `policy_version_id` string
      - `policy_set_id` string
      - `policy_set_name` string
      - `policy_set_version` integer
      - `effect` 'permit' | 'forbid'
  - `reason` string — Human-readable explanation of the decision, suitable for presenting to end users.
  - `diagnostics` PdpDiagnosticEntry[]
    - `policy_id` string
    - `message` string
  - `evaluated_at` string, date-time, required
  - `entity_snapshot` PdpEntitySnapshot
    - `principal` union
      - PdpUserSnapshot — Subset of the IAM User entity relevant to Cedar evaluation. All fields match the IAM management API User schema.
        - `type` 'user', required
        - `id` string, required — User public ID (same as IAM management API).
        - `email` string, required
        - `email_verified` boolean
      - PdpApplicationSnapshot — Subset of the IAM Application entity relevant to Cedar evaluation. All fields match the IAM management API Application schema.
        - `type` 'application', required
        - `id` string, required — Application public ID (same as IAM management API).
        - `name` string, required
        - `registration_method` 'managed' | 'dcr', required
        - `credential_type` string — Present only when resolved via credential lookup.
        - `dependencies` PdpResourceSnapshot[] — Resources this application depends on.
          - `id` string, required — Resource public ID (same as IAM management API).
          - `identifier` string, required
          - `name` string, required
          - `scopes` string[]
    - `resource` PdpResourceSnapshot — Subset of the IAM Resource entity relevant to Cedar evaluation. All fields match the IAM management API Resource schema.
      - `id` string, required — Resource public ID (same as IAM management API).
      - `identifier` string, required
      - `name` string, required
      - `scopes` string[]
    - `subject` union — Present when subject_type/subject_id were provided.
      - PdpUserSnapshot — Subset of the IAM User entity relevant to Cedar evaluation. All fields match the IAM management API User schema.
        - `type` 'user', required
        - `id` string, required — User public ID (same as IAM management API).
        - `email` string, required
        - `email_verified` boolean
      - PdpApplicationSnapshot — Subset of the IAM Application entity relevant to Cedar evaluation. All fields match the IAM management API Application schema.
        - `type` 'application', required
        - `id` string, required — Application public ID (same as IAM management API).
        - `name` string, required
        - `registration_method` 'managed' | 'dcr', required
        - `credential_type` string — Present only when resolved via credential lookup.
        - `dependencies` PdpResourceSnapshot[] — Resources this application depends on.
          - `id` string, required — Resource public ID (same as IAM management API).
          - `identifier` string, required
          - `name` string, required
          - `scopes` string[]
    - `context` object — The assembled Cedar context record.

## Other responses

- `400` — Bad Request - invalid input or validation error. Common causes: - Schema validation error (action/principal/resource doesn't exist in schema) - Entity not found (invalid principal_id, subject_id, or resource_id) - Policy source error (policy/policy set/version not found, draft doesn't exist) - Unsupported schema version - Invalid Cedar policy syntax (when using 'raw' source with validate=true)
- `401` — unauthorized error response when caller session is not authenticated
- `403` — forbidden error response when caller does not have permissions to a resource
- `429` — rate limit exceeded error response when caller has exhausted api limits for the given time period
- `500` — internal server error response when server encountered error of its own creation
- `503` — service unavailable error when server you're attempting to reach is not available
- `default` — internal server error response when server encountered error of its own creation

---

[API](https://skmtc.net/keycardai/apis/untitled-api.md) · [All operations](https://skmtc.net/keycardai/apis/untitled-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keycardai/untitled-api/revisions/2f5033ed4491/schema)