AuthZen API Implementation

[aaguiarz]

Description

What problem is being solved?

How is it being solved?

What changes are made to solve it?

References

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

• New Features

  • Introduced AuthZEN authorization API for single and batch checks, including configurable batch evaluation semantics.
  • Added endpoints to search subjects, resources, and actions, plus standardized pagination for search and batch operations.
  • Added PDP configuration discovery endpoint exposing policy decision point metadata and endpoints.

• Documentation

  • AuthZEN API and OpenAPI docs added with examples; API definitions are experimental and may change before GA.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4e7bd28b-bd35-4d75-9d41-98e1f92d5f59

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

Adds a new AuthZen gRPC/REST API: service definition, domain messages, batch evaluation semantics, search endpoints, PDP configuration discovery, OpenAPI documentation, and a README note marking the API as experimental.

Changes

Cohort / File(s)	Summary
Documentation README.md	Added "AuthZEN API Status" under Usage noting API definitions are experimental and may change.
Protocol Buffer Service authzen/v1/authzen_service.proto	New AuthZenService with RPCs: Evaluation, Evaluations, SubjectSearch, ResourceSearch, ActionSearch, GetConfiguration. Adds Subject/Resource/Action models and filters, evaluation request/response envelopes, batch semantics enum, pagination messages, validation rules, and OpenAPI HTTP bindings/metadata.
OpenAPI Specification docs/openapiv2/apidocs.swagger.json	Added AuthZen endpoints and definitions (evaluation, evaluations, subject/resource/action searches, configuration), new schemas (PageRequest/PageResponse, Evaluations*, GetConfigurationResponse, Subject/Resource/Action and filters), examples, and expanded error mappings.
Lint/Config buf.yaml	Added authzen/v1/authzen_service.proto to several buf ignore lists for enum lint rules (ENUM_VALUE_UPPER_SNAKE_CASE, ENUM_VALUE_PREFIX, ENUM_ZERO_VALUE_SUFFIX).

Sequence Diagram

sequenceDiagram
    participant Client
    participant AuthZenService
    participant PDP as Policy Decision Point

    Client->>AuthZenService: POST /stores/{store_id}/access/v1/evaluation\nEvaluationRequest (subject, resource, action, context)
    AuthZenService->>AuthZenService: Validate request, apply options/semantic
    AuthZenService->>PDP: Evaluate request / batch items
    PDP-->>AuthZenService: Decision(s) + context/metadata
    AuthZenService-->>Client: EvaluationResponse / EvaluationsResponse (decisions, context, errors)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'AuthZen API Implementation' accurately reflects the main change—introducing a comprehensive AuthZEN gRPC/REST API interface with service definitions, domain models, and endpoint mappings.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch poc/authzen

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Copilot reviewed 5 out of 7 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 7 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 8 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[aaguiarz]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 8 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@authzen/v1/authzen_service.proto`:
- Around line 495-498: The evaluations repeated field currently only has
(validate.rules).repeated.min_items = 1 on the field `evaluations` (type
`EvaluationsItemRequest`) which allows unbounded batches; add a
`(validate.rules).repeated.max_items = 100` (or another agreed upper bound) to
the same options block so the proto and generated OpenAPI include a maxItems
ceiling and prevent excessively large requests.
- Around line 1-697: The authzen_service.proto file (service AuthZenService and
its messages) is not formatted and its generated OpenAPI/docs are out of sync;
run the repository's proto format and generation flow (e.g., run buf format -w
on authzen_service.proto and then run the project's proto generation step such
as buf generate or the repo's make/script that produces the OpenAPI/Swagger
artifacts), regenerate the derived docs/OpenAPI, review the diffs, and commit
the updated proto and generated artifacts so CI passes.
- Around line 392-397: EvaluationsItemRequest currently allows empty items;
update the proto to enforce that each EvaluationsItemRequest contains at least
one of subject, resource, or action (e.g., by adding a validation rule or
converting to a oneof/required-group for subject | resource | action) so that an
item like {} is rejected, and apply the same validation intent to
EvaluationsRequest items (even though evaluations has min_items = 1) to prevent
empty entries; also add contract tests that send { "evaluations": [{}] } and
assert validation failure. Ensure you modify the EvaluationsItemRequest message
(fields: subject, resource, action, context) and add/enable the appropriate
validation annotations your build uses (e.g., PGV or buf.validate) and
corresponding test cases.

In `@docs/openapiv2/apidocs.swagger.json`:
- Around line 35-103: The checked-in apidocs.swagger.json was hand-edited;
revert manual changes and instead update the proto/source annotations that
generate the "/.well-known/authzen-configuration/{store_id}" endpoint (look for
the RPC/annotation that yields operationId "GetConfiguration" and its OpenAPI
options), then run the generator via the Makefile target or
scripts/update_swagger.sh to regenerate apidocs.swagger.json; ensure the same
fix is applied for the other mentioned hunks (lines ~385-877 and ~2249-3502) by
editing the proto annotations and re-running the generator rather than editing
JSON directly.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f8507159-2a89-44cb-885a-b7a471065de1

📥 Commits

Reviewing files that changed from the base of the PR and between 622ddd2 and 8569888.

⛔ Files ignored due to path filters (2)

• proto/authzen/v1/authzen_service.pb.go is excluded by !**/*.pb.go
• proto/authzen/v1/authzen_service_grpc.pb.go is excluded by !**/*.pb.go

📒 Files selected for processing (4)

• authzen/v1/authzen_service.proto
• buf.yaml
• docs/openapiv2/apidocs.swagger.json
• proto/authzen/v1/authzen_service.pb.validate.go

[Copilot]

Pull request overview

Copilot reviewed 6 out of 8 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 8 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.