AuthZEN Access Request Catalog Profile - Draft 1

Table of Contents

1. Introduction

An Access Request submitted after a requestable denial often carries more than the Subject, Resource, and Action of the denied evaluation. Deployments ask the requester which application, which entitlement, which role, or which cost center the request concerns. Those values are not free text: they are drawn from catalogs that are large, that change continuously, and that are scoped to what a particular requester is permitted to see.¶

The AuthZEN Access Request and Approval Profile [ARAP] lets a Policy Decision Point (PDP) publish a machine-readable description of those additional submission fields through the request_schema_url member of a requestable denial. JSON Schema [I-D.bhutton-json-schema] describes the shape and constraints of the data a submission must carry, but it has no vocabulary for remote, requester-scoped enumeration. A static enum embedded in the schema does not work when a catalog holds tens of thousands of entries, when the entitlements that are valid depend on the application the requester selected first, or when two requesters must see different subsets of the same catalog.¶

A catalog is also an authorization boundary in its own right. The set of applications, entitlements, roles, or cost centers a requester is permitted to see is itself sensitive: it discloses organizational structure, policy shape, and finance master data. A catalog surface therefore needs authentication, authorization, and scoping rules, not only a data format.¶

This profile defines that surface. It adds:¶

• A Catalogs Document (Section 6), a sibling artifact to the form schema that maps form fields to the catalogs backing them.¶

• A Catalog Endpoint protocol (Section 7) for searching, scoping, and paginating a catalog.¶

• A Catalog Response format (Section 8) carrying Catalog Items with well-known presentation and triage metadata.¶

• One member, request_catalogs_url, of the requestable denial's access_request object (Section 5).¶

This document is a profile of [ARAP] in the sense defined by the Extensibility and Profiles section of that specification, and through it a profile of the AuthZEN Authorization API [AuthZEN]. It populates the context.access_request extension point defined by [ARAP] with a single member, and defines extension points of its own (Section 12). It modifies no other part of [ARAP]: Access Request submission, Task Handles, completion semantics, and re-evaluation are unchanged.¶

This profile does not define an entitlement or catalog data model beyond the members a PEP needs to select and submit a value. It does not define provisioning or fulfillment. It does not define an agent-protocol transport or discovery mechanism. It does not define a user-interface rendering vocabulary.¶

2. Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

The terms Policy Decision Point (PDP), Policy Enforcement Point (PEP), Subject, Resource, Action, Context, and Decision are used as defined by [AuthZEN].¶

3. Terminology

This specification uses the terms Policy Enforcement Point (PEP), Policy Decision Point (PDP), Access Request, Access Request Service, Access Request Endpoint, requestable denial, and Task Handle as defined in [ARAP], and the terms Subject, Resource, Action, Context, and Decision Context as defined in [AuthZEN].¶

This specification defines the following additional terms.¶

Form Schema:

The machine-readable description of the augmentations a PEP adds to an Access Request submission's context and requested_access objects, referenced by the request_schema_url member of a requestable denial and RECOMMENDED by [ARAP] to be a JSON Schema [I-D.bhutton-json-schema] document.¶

Form Data Instance:

The JSON instance a PEP constructs to satisfy the Form Schema, and into which catalog-resolved values are placed. JSON Pointers appearing in a Catalogs Document are evaluated against this instance.¶

Catalog:

A set of selectable values backing one or more Form Schema fields, for example applications, entitlements, roles, or cost centers.¶

Catalogs Document:

A JSON document, referenced by request_catalogs_url, that maps Form Schema fields to the Catalog Endpoints from which their values are resolved (Section 6).¶

Catalog Reference:

The object within a Catalogs Document that describes how the value of a single Form Schema field is resolved.¶

Catalog Endpoint:

An HTTP endpoint that returns a paginated, authorized, requester-scoped list of Catalog Items for a Catalog (Section 7).¶

Catalog Item:

A single selectable entry returned by a Catalog Endpoint, carrying the value the PEP places into a Form Schema field along with OPTIONAL presentation and triage metadata.¶

Catalog Response:

The JSON object a Catalog Endpoint returns for a successful request (Section 8).¶

4. Protocol Overview

1. The PEP evaluates access using the AuthZEN Access Evaluation API and receives a requestable denial as defined by [ARAP].¶

2. The requestable denial carries both request_schema_url and request_catalogs_url in its context.access_request object.¶

3. The PEP verifies that both URLs resolve to hosts trusted under the deployment (Section 14.1), then fetches the Form Schema and the Catalogs Document.¶

4. For each Form Schema field named in the Catalogs Document, the PEP calls the Catalog Endpoint named by that field's Catalog Reference, supplying a search term and any scope parameters resolved from fields already populated in the Form Data Instance.¶

5. The PEP places the value identified by value_path in the chosen Catalog Item into the Form Data Instance, then repeats step 4 for any dependent field whose scope parameters have now become resolvable.¶

6. The PEP submits the Access Request to the Access Request Endpoint, carrying the completed Form Data Instance as the augmentations to the submission's context and requested_access objects.¶

7. The Access Request Service re-validates every submitted catalog identifier before accepting the submission.¶

Everything after submission proceeds exactly as defined in [ARAP]: the Access Request Service returns a Task Handle, the PEP polls the task or receives a callback, and an approved task is enforced through a new AuthZEN Authorization API evaluation. This profile changes none of that.¶

5. Requestable Denial Extension

This profile defines one additional member of the access_request object in the Decision Context of a requestable denial, added at the extension point defined by the Extensibility and Profiles section of [ARAP].¶

request_catalogs_url:

OPTIONAL. HTTPS URI. URL of a Catalogs Document describing how the PEP resolves form fields whose values are selected from a backing catalog. See Section 6.¶

PEPs interacting with deployments that do not include request_catalogs_url MAY omit Catalog Endpoint resolution entirely.¶

The Catalogs Document is a sibling artifact to the Form Schema; it does not modify or extend the JSON Schema referenced by request_schema_url. A PDP MUST include request_schema_url when including request_catalogs_url.¶

The following is a non-normative example:¶

{
  "decision": false,
  "context": {
    "evaluation_id": "eval_01HX4Y2P8BQ4Y3F0V0K9D6Z7M1",
    "evaluated_at": "2026-04-30T20:15:00Z",
    "reason": "approval_required",
    "access_request": {
      "endpoint": "https://pdp.example.com/access/v1/requests",
      "template": "application_access",
      "expires_at": "2026-04-30T20:25:00Z",
      "binding_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6InBkcC0xIn0.eyJldmFsdWF0aW9uX2lkIjoiZXZhbF8wMUhYNFkyUDhCUTRZM0YwVjBLOUQ2WjdNMSJ9.bXBfc2lnbmF0dXJl",
      "form_url": "https://requests.example.com/forms/application_access",
      "request_schema_url": "https://requests.example.com/schemas/application_access.json",
      "request_catalogs_url": "https://requests.example.com/catalogs/application_access.json",
      "display": {
        "title": "Request access",
        "description": "Manager approval is required before this document can be opened."
      }
    }
  }
}

6. Catalogs Document

The Catalogs Document is a JSON object retrieved from request_catalogs_url using the HTTP GET method as defined in [RFC9110]. It has the following members:¶

fields:

REQUIRED. Object. Each member name is a JSON Pointer ([RFC6901]) into the form data instance described by the form schema, identifying a field whose value is selected from a catalog. Each member value is a Catalog Reference object.¶

Implementations MAY include additional members for documentation or vendor metadata; consumers MUST ignore members they do not recognize.¶

A Catalog Reference object has the following members:¶

endpoint:

REQUIRED. HTTPS URI. Catalog Endpoint from which catalog items are retrieved.¶

search_param:

OPTIONAL. String. Query parameter used to pass a free-text search term to the Catalog Endpoint. Defaults to q.¶

scope_params:

OPTIONAL. Object. Each member name is the query parameter sent to the Catalog Endpoint and the value is a JSON Pointer ([RFC6901]) into the form data instance identifying the source field. The PEP MUST resolve each pointer at request time and MUST NOT call the Catalog Endpoint until every referenced source field has a value.¶

value_path:

OPTIONAL. String. JSON Pointer ([RFC6901]) into a Catalog Item, identifying the value the PEP places into the form field. Defaults to /value.¶

label_path:

OPTIONAL. String. JSON Pointer ([RFC6901]) into a Catalog Item, identifying a human-readable label. Defaults to /label.¶

Non-normative example:¶

{
  "fields": {
    "/application_id": {
      "endpoint": "https://requests.example.com/catalog/applications",
      "search_param": "q"
    },
    "/entitlement_id": {
      "endpoint": "https://requests.example.com/catalog/entitlements",
      "search_param": "q",
      "scope_params": { "application_id": "/application_id" }
    }
  }
}

7. Catalog Endpoint

A Catalog Endpoint accepts an HTTP GET request as defined in [RFC9110] and returns a paginated list of Catalog Items.¶

The Catalog Endpoint MUST accept the following query parameters:¶

• The search parameter named by search_param (default q): String. Free-text query supplied by the caller.¶

• The scope parameters named by scope_params: String values taken from other form data fields.¶

• cursor: OPTIONAL. String. Opaque pagination cursor returned by a previous response.¶

• limit: OPTIONAL. Integer. Caller-requested page size. The Catalog Endpoint MAY clamp or ignore this value.¶

The Catalog Endpoint MAY accept additional deployment-specific parameters; receivers MUST ignore parameters they do not recognize.¶

Catalog Endpoints are protected APIs. Their authentication and credential rules are defined in Section 11.¶

A Catalog Endpoint MUST:¶

• authenticate the caller;¶

• authorize the caller to enumerate the catalog; and¶

• return only items the caller is permitted to see for the original Subject, Resource, and Action.¶

The catalog response is itself an authorization boundary; it MUST NOT disclose entries the requester would not be permitted to request.¶

8. Catalog Response

A successful response returns HTTP 200 OK and a JSON object with the following members:¶

items:

REQUIRED. Array of Catalog Items. Each Catalog Item is a JSON object containing the value identified by value_path and SHOULD include the value identified by label_path. Items SHOULD include the following well-known optional members when applicable, and MAY include additional vendor-specific metadata:¶

• description: String. Human-readable description of the item.¶

• risk_level: String. Risk classification used by the deployment (for example, low, medium, high). Useful for agent and human triage.¶

• granted: Boolean. When true, indicates that the requester already has access to the item. Allows a PEP to suppress redundant or no-op Access Request submissions.¶

• owner: Object or String. Identifier or reference for the item's owner, when the catalog tracks ownership.¶

next_cursor:

OPTIONAL. String. Opaque cursor that the caller passes as cursor to retrieve the next page. Absent when no further pages are available.¶

total:

OPTIONAL. Integer. Approximate total number of items matching the search and scope filters. Used as a hint only; the PEP MUST NOT rely on its accuracy.¶

Non-normative example:¶

GET /catalog/entitlements?application_id=app_123&q=customer&limit=2 HTTP/1.1
Host: requests.example.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Accept: application/json

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

{
  "items": [
    {
      "value": "ent_abc",
      "label": "Customer Records (Read)",
      "description": "Read access to customer master data"
    },
    {
      "value": "ent_def",
      "label": "Customer Records (Write)",
      "description": "Write access to customer master data",
      "risk_level": "high"
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjJ9"
}

9. Agent Protocol Catalogs

Deployments serving agentic PEPs MAY additionally expose catalogs through an agent protocol. When such a protocol is used, each catalog SHOULD be exposed as a resource whose identifier or URI template encodes the same scope parameters described by scope_params (for example, entitlements://{application_id}). Resource read responses SHOULD use the Catalog Response shape defined in Section 8.¶

This profile does not define agent-protocol discovery or transport. When both an HTTP Catalog Endpoint and an agent-protocol catalog are exposed, they MUST return the same Catalog Items for equivalent scope parameters.¶

10. Processing Rules

11. Authorization and Authentication

Catalog Endpoints are protected APIs. Support for OAuth 2.0 [RFC6749] is RECOMMENDED. When OAuth 2.0 bearer tokens are used, Catalog Endpoints MUST follow [RFC6750].¶

A Catalog Endpoint SHOULD share an origin with the Access Request Endpoint and SHOULD accept the same caller credentials. Deployments that host catalogs on a different origin MUST establish a documented mechanism for obtaining credentials accepted by the Catalog Endpoint, for example through OAuth 2.0 Token Exchange [RFC8693]; this profile does not define cross-origin credential acquisition.¶

Authorization for a Catalog Endpoint call is bound to the original Subject, Resource, and Action of the denied evaluation rather than to a specific access token, session, or PEP instance. The Access Request Service MUST authorize each catalog call independently: authorization to submit an Access Request does not imply authorization to enumerate every catalog the deployment operates.¶

12. Extensibility

This profile populates the context.access_request extension point defined by [ARAP] with the request_catalogs_url member (Section 5).¶

This profile defines three additional extension points. Additional members MAY appear at these locations, and those members MUST follow the naming rules in the Naming Extensions section of [ARAP]:¶

• A Catalogs Document (Section 6).¶

• A Catalog Reference object within a Catalogs Document (Section 6).¶

• A Catalog Item within a Catalog Response (Section 8).¶

An implementation receiving a member it does not recognize at an extension point defined by this profile MUST ignore it and MUST NOT fail processing on the basis of the unrecognized name. An implementation MAY surface unrecognized members in audit records or to a human requester, subject to the rule in Section 10.1 that unknown Catalog Item members are informational only.¶

Registry-eligible member names introduced by this profile are registered in Section 16.1.¶

13. Privacy Considerations

Search terms and scope parameters sent to a Catalog Endpoint reveal what the requester is looking for before any Access Request is submitted, and may themselves be personal data. A partially typed search term discloses requester intent even when no Access Request follows.¶

Catalog Endpoints SHOULD minimize the logging and retention of query strings, and SHOULD retain them only as long as required by business, security, and compliance policy.¶

Catalog Item metadata can identify people. The owner member in particular names or references an individual, and MUST only be returned to callers authorized to receive it.¶

PEPs SHOULD NOT cache Catalog Responses beyond the request interaction that produced them. Catalog contents are scoped to the requester and to the Subject, Resource, and Action of the denied evaluation, so a cached response can outlive both the authorization that produced it and the accuracy of the items it holds.¶

14. Security Considerations

15. IANA Considerations

This specification makes no requests of IANA.¶

16. OpenID Foundation Registry Considerations

17. References

Appendix A. Examples

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

{
  "decision": false,
  "context": {
    "evaluation_id": "eval_01HX4Y2P8BQ4Y3F0V0K9D6Z7M1",
    "evaluated_at": "2026-04-30T20:15:00Z",
    "reason": "approval_required",
    "access_request": {
      "endpoint": "https://pdp.example.com/access/v1/requests",
      "template": "application_access",
      "expires_at": "2026-04-30T20:25:00Z",
      "binding_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6InBkcC0xIn0.eyJldmFsdWF0aW9uX2lkIjoiZXZhbF8wMUhYNFkyUDhCUTRZM0YwVjBLOUQ2WjdNMSJ9.bXBfc2lnbmF0dXJl",
      "form_url": "https://requests.example.com/forms/application_access",
      "request_schema_url": "https://requests.example.com/schemas/application_access.json",
      "request_catalogs_url": "https://requests.example.com/catalogs/application_access.json"
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://requests.example.com/schemas/application_access.json",
  "type": "object",
  "properties": {
    "application_id": { "type": "string" },
    "entitlement_id": { "type": "string" },
    "business_justification": { "type": "string" },
    "requested_until": { "type": "string", "format": "date-time" }
  },
  "required": [
    "application_id",
    "entitlement_id",
    "business_justification"
  ]
}

{
  "fields": {
    "/application_id": {
      "endpoint": "https://requests.example.com/catalog/applications",
      "search_param": "q"
    },
    "/entitlement_id": {
      "endpoint": "https://requests.example.com/catalog/entitlements",
      "search_param": "q",
      "scope_params": { "application_id": "/application_id" }
    }
  }
}

GET /catalog/applications?q=crm&limit=2 HTTP/1.1
Host: requests.example.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Accept: application/json

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

{
  "items": [
    {
      "value": "app_123",
      "label": "CRM",
      "description": "Customer relationship management platform"
    },
    {
      "value": "app_456",
      "label": "CRM Analytics",
      "description": "Reporting and analytics over CRM data",
      "granted": true
    }
  ],
  "total": 2
}

GET /catalog/entitlements?application_id=app_123&q=customer&limit=2 HTTP/1.1
Host: requests.example.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Accept: application/json

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

{
  "items": [
    {
      "value": "ent_abc",
      "label": "Customer Records (Read)",
      "description": "Read access to customer master data"
    },
    {
      "value": "ent_def",
      "label": "Customer Records (Write)",
      "description": "Write access to customer master data",
      "risk_level": "high"
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjJ9"
}

POST /access/v1/requests HTTP/1.1
Host: pdp.example.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Content-Type: application/json
Idempotency-Key: 7b8d0f0d-65a1-4af1-9fd3-a684f08a5d13

{
  "subject": {
    "type": "user",
    "id": "alice@example.com"
  },
  "resource": {
    "type": "document",
    "id": "q4-plan"
  },
  "action": {
    "name": "can_read"
  },
  "context": {
    "business_justification": "Needed for customer renewal review"
  },
  "requested_access": {
    "application_id": "app_123",
    "entitlement_id": "ent_abc",
    "requested_until": "2026-05-01T00:15:00Z"
  },
  "denial": {
    "evaluation_id": "eval_01HX4Y2P8BQ4Y3F0V0K9D6Z7M1",
    "evaluated_at": "2026-04-30T20:15:00Z",
    "expires_at": "2026-04-30T20:25:00Z",
    "reason": "approval_required",
    "binding_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6InBkcC0xIn0.eyJldmFsdWF0aW9uX2lkIjoiZXZhbF8wMUhYNFkyUDhCUTRZM0YwVjBLOUQ2WjdNMSJ9.bXBfc2lnbmF0dXJl",
    "template": "application_access"
  }
}

Appendix B. Implementation Considerations

This appendix describes common deployment patterns and is non-normative.¶

Appendix C. Design Rationale

This appendix records non-obvious design choices and the reasoning behind them. It is non-normative.¶

Appendix D. Acknowledgements

The author thanks the OpenID AuthZEN Working Group for discussion and review.¶

Appendix E. Document History

-00¶

• Initial version. Catalog references were moved here from the AuthZEN Access Request and Approval Profile so that the base profile remains a thin wire format.¶

Author's Address