Skip to content

contd: Update API endpoint summaries and descriptions #265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nick-gagliardi wants to merge 3 commits into
base: main
Choose a base branch
from
Open

contd: Update API endpoint summaries and descriptions #265

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6f50591
follow-on to @amanda's PR #263 to clean up experimental endpoints
nick-gagliardi Sep 30, 2026
8ffd0d4
regen/commit derived files for CI to resolve failing tests
nick-gagliardi Sep 30, 2026
e2ff0f8
fix v2
nick-gagliardi Sep 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 45 additions & 43 deletions authzen/v1/authzen_service.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,29 +18,29 @@ service AuthZenService {
};

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "[Experimental] Evaluate whether a subject can perform an action on a resource"
summary: "[Experimental] Check whether a subject can perform an action on a resource"

operation_id: "Evaluation"
description:
"[Experimental] The Evaluation API determines whether a subject is authorized to perform an action on a resource. "
"This endpoint implements the AuthZEN Access Evaluation API specification.\n\n"
"## Request Structure\n"
"The request requires three components:\n"
"## Request Structure\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nick-gagliardi , FYI: I still haven't figured out what is breaking the code blocks for these docs. Claude advised me it could be using headings like this but I wasn't able to figure it out in the first PR.

"The request requires three components:\n\n"
"- **subject**: The entity requesting access (e.g., a user or service)\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should these be capitalized like the similar resources are on line 38-40? I feel like they could be and it would still be fine.

"- **action**: The operation being performed (maps to a relation in the authorization model)\n"
"- **resource**: The object being accessed\n\n"
"Each component has a `type` and `id` field, and may include optional `properties` for ABAC (Attribute-Based Access Control) conditions.\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would possibly add text reference to ABAC (Attribute-Based Access Control)

"## Response\n"
"## Response\n\n"
"The response contains a `decision` field (boolean) indicating whether access is permitted, "
"and an optional `context` object with additional information such as the evaluation ID or error details.\n\n"
"## ABAC Support\n"
"Properties on subject, action, and resource are automatically merged into the evaluation context with prefixes:\n"
"## ABAC Support\n\n"
"Properties on subject, action, and resource are automatically merged into the evaluation context with prefixes:\n\n"
"- Subject properties: `subject_<property_name>`\n"
"- Resource properties: `resource_<property_name>`\n"
"- Action properties: `action_<property_name>`\n\n"
"These merged properties can be used in conditions defined in your authorization model.\n\n"
"## Examples\n"
"### Basic authorization check\n"
"## Examples\n\n"
"### Basic authorization check\n\n"
"Check if user Anne can read a document:\n"
"```json\n"
"{\n"
Expand All @@ -54,8 +54,8 @@ service AuthZenService {
"{\n"
" \"decision\": true\n"
"}\n"
"```\n"
"### Using properties for ABAC\n"
"```\n\n"
"### Using properties for ABAC\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"### Using properties for ABAC\n\n"
"### Use properties for ABAC\n\n"

"Check access with subject and resource attributes:\n"
"```json\n"
"{\n"
Expand All @@ -71,8 +71,8 @@ service AuthZenService {
" \"properties\": {\"classification\": \"confidential\", \"required_clearance\": 2}\n"
" }\n"
"}\n"
"```\n"
"### Using request context\n"
"```\n\n"
"### Using request context\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"### Using request context\n\n"
"### Use request context\n\n"

"Provide additional context for time-based or environmental conditions:\n"
"```json\n"
"{\n"
Expand All @@ -85,8 +85,8 @@ service AuthZenService {
" \"is_vpn_connected\": true\n"
" }\n"
"}\n"
"```\n"
"### Specifying authorization model\n"
"```\n\n"
"### Specifying authorization model\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"### Specifying authorization model\n\n"
"### Specify authorization model\n\n"

"Pin the evaluation to a specific authorization model version using the `Openfga-Authorization-Model-Id` header:\n"
"```\n"
"POST /stores/{store_id}/access/v1/evaluation\n"
Expand All @@ -108,22 +108,22 @@ service AuthZenService {
};

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "[Experimental] Check whether one or more users are authorized to access resources"
summary: "[Experimental] Check multiple authorizations in a single request"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One of the endpoints in the other file is specific about CheckRequest or maybe CheckUpdate? But, I would also update this endpoint to replace Check with Evaluate so users don't get confused.


operation_id: "Evaluations"
description:
"[Experimental] The Evaluations API allows batch authorization checks in a single request. "
"It supports request-level defaults for subject, action, resource, and context that can be overridden per evaluation item.\n\n"
"## Evaluation Semantics\n"
"The `options.evaluations_semantic` field controls how evaluations are processed:\n"
"## Evaluation Semantics\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"## Evaluation Semantics\n\n"
"## Evaluation semantics\n\n"

"The `options.evaluations_semantic` field controls how evaluations are processed:\n\n"
"- `execute_all` (default): Execute all evaluations and return all results\n"
"- `deny_on_first_deny`: Stop processing on first deny decision\n"
"- `permit_on_first_permit`: Stop processing on first permit decision\n\n"
"When using `deny_on_first_deny` or `permit_on_first_permit`, the response may include fewer items than the request because processing short-circuits when the condition is met.\n\n"
"## Authorization Model Selection\n"
"## Authorization Model Selection\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"## Authorization Model Selection\n\n"
"## Authorization Model selection\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The other headings seem to be in sentence case.

"To pin evaluations to a specific authorization model version, send the `Openfga-Authorization-Model-Id` header. If the header is not provided, the latest model is used.\n\n"
"## Examples\n"
"### Basic batch evaluation\n"
"## Examples\n\n"
"### Basic batch evaluation\n\n"
"Check if a user can perform multiple actions on a document:\n"
"```json\n"
"{\n"
Expand All @@ -135,8 +135,8 @@ service AuthZenService {
" {\"action\": {\"name\": \"can_delete\"}}\n"
" ]\n"
"}\n"
"```\n"
"### Using evaluation semantics\n"
"```\n\n"
"### Using evaluation semantics\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"### Using evaluation semantics\n\n"
"### Use evaluation semantics\n\n"

"Stop on first permitted action (useful for finding any valid permission):\n"
"```json\n"
"{\n"
Expand All @@ -150,8 +150,8 @@ service AuthZenService {
" \"evaluations_semantic\": \"permit_on_first_permit\"\n"
" }\n"
"}\n"
"```\n"
"### Overriding defaults per evaluation\n"
"```\n\n"
"### Overriding defaults per evaluation\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"### Overriding defaults per evaluation\n\n"
"### Override defaults per evaluation\n\n"

"Check permissions across multiple resources:\n"
"```json\n"
"{\n"
Expand Down Expand Up @@ -181,8 +181,9 @@ service AuthZenService {
"[Experimental] The SubjectSearch API returns all subjects that have a specific action (relation) on a given resource. "
"This is useful for answering questions like \"Who can read this document?\" or \"Who can administer this folder?\"\n\n"
"Results can be filtered by subject type and support pagination for large result sets.\n\n"
"## Examples\n"
"### Find all users who can read a document\n"
"> **Note:** The `subject.id` field may be provided but is ignored, per the AuthZEN spec — only `subject.type` is used to filter results.\n\n"
Comment thread
coderabbitai[bot] marked this conversation as resolved.
"## Examples\n\n"
"### Find all users who can read a document\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"### Find all users who can read a document\n\n"
"### Find all users with permission to read a document\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This kind of sounds like you're trying to find literate users. Maybe this should be authorized instead?

"```json\n"
"{\n"
" \"resource\": {\"type\": \"document\", \"id\": \"roadmap\"},\n"
Expand All @@ -200,17 +201,17 @@ service AuthZenService {
" ],\n"
" \"page\": {\"count\": 3}\n"
"}\n"
"```\n"
"### Paginated search with limit\n"
"```\n\n"
"### Paginated search with limit\n\n"
"```json\n"
"{\n"
" \"resource\": {\"type\": \"folder\", \"id\": \"engineering\"},\n"
" \"action\": {\"name\": \"can_view\"},\n"
" \"subject\": {\"type\": \"user\"},\n"
" \"page\": {\"limit\": 10}\n"
"}\n"
"```\n"
"### Continue from previous page\n"
"```\n\n"
"### Continue from previous page\n\n"
"```json\n"
"{\n"
" \"resource\": {\"type\": \"folder\", \"id\": \"engineering\"},\n"
Expand All @@ -236,8 +237,9 @@ service AuthZenService {
"[Experimental] The ResourceSearch API returns all resources of a given type that a subject has a specific action (relation) on. "
"This is useful for answering questions like \"What documents can Anne read?\" or \"What folders can Bob administer?\"\n\n"
"The resource type filter is required. Results support pagination for large result sets.\n\n"
"## Examples\n"
"### Find all documents a user can read\n"
"> **Note:** The `resource.id` field may be provided but is ignored, per the AuthZEN spec — only `resource.type` is used to filter results.\n\n"
"## Examples\n\n"
"### Find all documents a user can read\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"### Find all documents a user can read\n\n"
"### Find all documents a user is authorized to read\n\n"

"```json\n"
"{\n"
" \"subject\": {\"type\": \"user\", \"id\": \"anne\"},\n"
Expand All @@ -255,17 +257,17 @@ service AuthZenService {
" ],\n"
" \"page\": {\"count\": 3}\n"
"}\n"
"```\n"
"### Find folders a user can administer with pagination\n"
"```\n\n"
"### Find folders a user can administer with pagination\n\n"
"```json\n"
"{\n"
" \"subject\": {\"type\": \"user\", \"id\": \"bob\"},\n"
" \"action\": {\"name\": \"can_admin\"},\n"
" \"resource\": {\"type\": \"folder\"},\n"
" \"page\": {\"limit\": 25}\n"
"}\n"
"```\n"
"### Search with ABAC context\n"
"```\n\n"
"### Search with ABAC context\n\n"
"```json\n"
"{\n"
" \"subject\": {\"type\": \"user\", \"id\": \"anne\"},\n"
Expand Down Expand Up @@ -294,8 +296,8 @@ service AuthZenService {
"[Experimental] The ActionSearch API returns all actions (relations) that a subject can perform on a specific resource. "
"This is useful for answering questions like \"What can Anne do with this document?\" or building dynamic UIs "
"that show only the actions a user is permitted to perform.\n\n"
"## Examples\n"
"### Find all actions a user can perform on a document\n"
"## Examples\n\n"
"### Find all actions a user can perform on a document\n\n"
"```json\n"
"{\n"
" \"subject\": {\"type\": \"user\", \"id\": \"anne\"},\n"
Expand All @@ -312,8 +314,8 @@ service AuthZenService {
" ],\n"
" \"page\": {\"count\": 3}\n"
"}\n"
"```\n"
"### Search with ABAC context for time-based permissions\n"
"```\n\n"
"### Search with ABAC context for time-based permissions\n\n"
"```json\n"
"{\n"
" \"subject\": {\"type\": \"user\", \"id\": \"bob\"},\n"
Expand All @@ -323,8 +325,8 @@ service AuthZenService {
" \"user_department\": \"finance\"\n"
" }\n"
"}\n"
"```\n"
"### Paginated action search\n"
"```\n\n"
"### Paginated action search\n\n"
"```json\n"
"{\n"
" \"subject\": {\"type\": \"user\", \"id\": \"admin\"},\n"
Expand All @@ -347,7 +349,7 @@ service AuthZenService {
"supported endpoints, and capabilities. This endpoint follows the AuthZEN specification for PDP discovery.\n\n"
"Following the AuthZEN spec's multi-tenant pattern, OpenFGA provides a per-store discovery endpoint at "
"`/.well-known/authzen-configuration/{store_id}`. This returns absolute endpoint URLs specific to that store.\n\n"
"## Example Response\n"
"## Example Response\n\n"

@avanscoy avanscoy Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"## Example Response\n\n"
"## Example response\n\n"

"```json\n"
"{\n"
" \"policy_decision_point\": \"https://example.com/stores/01ARZ3NDEKTSV4RRFFQ69G5FAV\",\n"
Expand Down
Loading
Loading