AuthZEN API reference: endpoints and JSON examples

By David Brossard · Last updated 3 November 2026

This page summarizes the OpenID AuthZEN Authorization API 1.0 (Final Specification, January 2026) with copy-paste JSON examples. All calls are HTTPS POST with Content-Type: application/json. A deny is a normal 200 response with "decision": false; HTTP 4xx/5xx codes mean transport or request errors.

On this page: Information model · Access Evaluation · Access Evaluations (batch) · Search APIs · PDP metadata & discovery · Try it

Information model: subject, action, resource, context

Element	Required fields	Optional	Example
`subject`	`type`, `id`	`properties`	`{"type":"user","id":"[email protected]","properties":{"department":"Sales"}}`
`action`	`name`	`properties`	`{"name":"can_read"}`
`resource`	`type`, `id`	`properties`	`{"type":"account","id":"123"}`
`context`	none (the whole object is optional)	any	`{"time":"1985-10-26T01:22-07:00"}`

The decision response carries a boolean decision (required) and an optional context object. The PDP can use context to return reasons, advice or obligations, or hints such as a step-up authentication requirement.

Access Evaluation API

Default path: /access/v1/evaluation. One question, one decision.

POST /access/v1/evaluation HTTP/1.1
Host: pdp.example.com
Content-Type: application/json
Authorization: Bearer <token>

{
  "subject":  { "type": "user", "id": "[email protected]" },
  "resource": { "type": "account", "id": "123" },
  "action":   { "name": "can_read", "properties": { "method": "GET" } },
  "context":  { "time": "1985-10-26T01:22-07:00" }
}

HTTP/1.1 200 OK
Content-Type: application/json

{ "decision": true }

A deny that includes a reason in the response context:

{
  "decision": false,
  "context": {
    "reason_user": { "en": "Accounts can only be read by their owner or a manager." }
  }
}

The shape of context is up to the PDP. The example above is illustrative.

Access Evaluations API (batch)

Default path: /access/v1/evaluations. Top-level subject, action, resource and context act as defaults that each item in evaluations can override. Typical use: deciding which buttons to show in a UI with a single round trip.

{
  "subject": { "type": "user", "id": "[email protected]" },
  "action":  { "name": "can_read" },
  "options": { "evaluations_semantic": "execute_all" },
  "evaluations": [
    { "resource": { "type": "document", "id": "boxcarring.md" } },
    { "resource": { "type": "document", "id": "subject-search.md" } },
    { "action": { "name": "can_edit" }, "resource": { "type": "document", "id": "boxcarring.md" } }
  ]
}

{
  "evaluations": [
    { "decision": true },
    { "decision": false },
    { "decision": false, "context": { "error": { "status": 404, "message": "Resource not found" } } }
  ]
}

options.evaluations_semantic controls execution:

execute_all (default): evaluate everything and return all decisions in request order.
deny_on_first_deny: stop at the first deny. Useful when all checks must pass.
permit_on_first_permit: stop at the first permit. Useful when any one check is enough.

Search APIs: subject, resource and action search

Search answers "who / what / which" questions without the N+1 problem of evaluating every item. Leave out the id of the entity you are searching for and send only its type.

API	Default path	Question
Subject Search	`/access/v1/search/subject`	Which users can read account 123?
Resource Search	`/access/v1/search/resource`	Which accounts can Alice read?
Action Search	`/access/v1/search/action`	What can Alice do on account 123?

Resource Search example

POST /access/v1/search/resource
{
  "subject":  { "type": "user", "id": "[email protected]" },
  "action":   { "name": "can_read" },
  "resource": { "type": "account" },
  "page":     { "limit": 2 }
}

{
  "page": { "next_token": "a3M9NDU2O3N6PTI=", "count": 2 },
  "results": [
    { "type": "account", "id": "123" },
    { "type": "account", "id": "456" }
  ]
}

Pagination: repeat the identical request with "page": { "token": "<next_token>" } until next_token is an empty string. count, total and properties are optional in the response page object.

PDP metadata and discovery

A PDP publishes its configuration at /.well-known/authzen-configuration, placed between the host and any path (for example https://pdp.example.com/.well-known/authzen-configuration/tenant1).

GET /.well-known/authzen-configuration HTTP/1.1
Host: pdp.example.com

{
  "policy_decision_point": "https://pdp.example.com",
  "access_evaluation_endpoint": "https://pdp.example.com/access/v1/evaluation",
  "access_evaluations_endpoint": "https://pdp.example.com/access/v1/evaluations",
  "search_subject_endpoint": "https://pdp.example.com/access/v1/search/subject",
  "search_resource_endpoint": "https://pdp.example.com/access/v1/search/resource",
  "search_action_endpoint": "https://pdp.example.com/access/v1/search/action"
}

policy_decision_point and access_evaluation_endpoint are required. Other endpoints are optional; if one is absent, the PEP treats that API as unsupported.
Optional: capabilities (registered capability URNs) and signed_metadata (a JWT whose values take precedence).

Try it

Send requests to a live AuthZEN PDP at pdp.alfa.guide (ALFA policies, by Axiomatics).
Read the normative text: Authorization API 1.0. Editors' draft: openid.github.io/authzen.
Find a PDP or PEP for your stack: AuthZEN implementations.