Nexus PDP: error responses on the AuthZen API, and the Nexus PDP API key in the how-tos

[EliMoshkovich]

This PR handles the two follow-ups from the final review of #657, updated over two review rounds.

AuthZen error responses (docs/concepts/pdp/overview.mdx, AuthZen compatibility): the old text said a bad request gets 400 invalid_request and a bad token gets 401 unauthorized. No PDP type sends AuthZen error codes, and the statuses differ by type. The section now has one table for the container PDP, Nexus PDP and the Cloud PDP, checked against each one's source; the Cloud PDP was also checked live against cloudpdp.api.permit.io:

Request	Container PDP	Nexus PDP	Cloud PDP
No Authorization header	401, text	401, {"message":"Unauthorized"}	401, {"message":"Unauthorized"}
No Bearer scheme	403, text	401, JSON	401, JSON
Wrong API key	403, text	401, JSON	403, {"message":"Forbidden"}
Invalid JSON / missing field / no JSON Content-Type / over 2 MB	400 / 422 / 415 / 413	same	same
evaluations item missing a field	400	400	400
Empty evaluations array	400, text	400, {"evaluations":[]}	400, {"evaluations":[]}

The section also covers scheme capitalization (only Bearer/bearer on Nexus PDP and the Cloud PDP), the Cloud PDP 429, and which checks run before the token on each type. Discovery answers without a token on Nexus PDP and the Cloud PDP.

Nexus PDP API key and setup:

• Get your API key, and the Prerequisites of the check, bulk-check, user-permissions, authorized-users and data-filtering how-tos, say that Permit Nexus PDP takes the Nexus PDP API key. They also link Deploy Nexus PDP next to Run the PDP.
• The overview's Nexus PDP section says how to point an SDK at it.
• The ABAC notes name Nexus PDP next to the Cloud PDP, and say that an ABAC check on Nexus PDP returns a deny, not an error.
• A separate commit drops the duplicated scheme from check's POST /allowed sample.

npm run build: 0 bad links, 0 bad anchors, 525/525 baseline routes.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for permitio-docs ready!

Name	Link
🔨 Latest commit	267d0a1
🔍 Latest deploy log	https://app.netlify.com/projects/permitio-docs/deploys/6abd56c0a3cbb30008afd301
😎 Deploy Preview	https://deploy-preview-661--permitio-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[linear-code]

PER-16042

PER-16666

PER-16667

PER-16668

[zeevmoney]

Changes requested: 1 HIGH, 2 MEDIUM, 3 LOW.

Blocking:

• HIGH docs/concepts/pdp/overview.mdx:380: the container PDP returns neither these statuses nor AuthZen error codes

Non-blocking:

• MEDIUM docs/concepts/pdp/overview.mdx:391: /access/v1/evaluations has 400 responses that come after the token check (plus 413)
• MEDIUM docs/how-to/enforce-permissions/user-permissions.mdx:142 (and authorized-users.mdx:146): the Nexus PDP key sentence is in the ABAC example, and Nexus PDP doesn't evaluate ABAC
• LOW docs/how-to/enforce-permissions/authorized-users.mdx:146: a raw <a> skips Docusaurus link handling
• LOW docs/how-to/enforce-permissions/check.mdx:13: the next prerequisite sends Nexus PDP readers to container and Cloud PDP setup
• LOW docs/overview/get-api-key.mdx:12: the first mention should be "Permit Nexus PDP", with a link

Outside this diff (not inline):

• MEDIUM docs/how-to/enforce-permissions/data-filtering.mdx:17,23: Nexus PDP feature parity sends readers here. The page still says to use the environment API key, and Nexus PDP rejects that key with 401. It needs the same Nexus PDP key sentence as check.mdx.
• LOW docs/concepts/pdp/overview.mdx:378: "Every AuthZen endpoint requires the header Authorization: Bearer" is true on the container PDP. On Nexus PDP, the discovery endpoint GET /.well-known/authzen-configuration answers without a token.

Details are in the inline comments on each line.

[EliMoshkovich]

Thanks Zeev. Everything is fixed in db345d3, and each inline thread has a reply and is resolved. The two outside-the-diff items:

• data-filtering.mdx (MEDIUM): the Prerequisites key bullet now carries the same Nexus PDP key sentence as check.mdx (the first mention links "Permit Nexus PDP"). Line 23 says <YOUR_API_KEY> is "the Nexus PDP API key on Nexus PDP".
• overview.mdx:378 (LOW): it now says the container PDP requires the bearer header on every AuthZen endpoint, and Nexus PDP on every one except discovery (GET /.well-known/authzen-configuration), which answers without a token. I confirmed Nexus's metadata handler never resolves a scope.

npm run build: 0 bad links, 0 bad anchors, 525/525 routes.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[zeevmoney]

Approved — no CRITICAL or HIGH issues found.

The previous review's six threads and its two items outside the diff are fixed. Each status in the error table matches the container PDP (pdp-server in permitio/PDP) and the Nexus PDP source.

Non-blocking:

• MEDIUM docs/concepts/pdp/overview.mdx:382: the error table and the bearer sentence leave out the Cloud PDP (wrong key gets 403 JSON; body checks come before the token)
• LOW docs/concepts/pdp/overview.mdx:385: Nexus PDP rejects BEARER with the right key, and the container PDP accepts it
• LOW docs/concepts/pdp/overview.mdx:393: the ordering paragraph leaves out the empty-array check and the missing-token case
• LOW docs/how-to/enforce-permissions/user-permissions.mdx:15 (and authorized-users.mdx:15, data-filtering.mdx:15): the PDP prerequisite doesn't link Deploy Nexus PDP, unlike check.mdx
• LOW docs/how-to/enforce-permissions/check.mdx:99: the ABAC note doesn't say that an ABAC check on Nexus PDP returns a deny
• LOW docs/how-to/enforce-permissions/check.mdx:181: the addresses to substitute add a second scheme to the sample URL

Outside this diff (not inline):

• MEDIUM docs/how-to/enforce-permissions/bulk-check.mdx:14: Nexus PDP feature parity lists bulk check as supported. This page has no API key bullet, though, so Nexus PDP readers get no key guidance, and the environment API key gets 401. It needs the same key bullet as check.mdx. Its "Combine ReBAC and ABAC checks" use case (line 44) also needs the ABAC note: on Nexus PDP the ABAC item returns a deny, so only the ReBAC check can allow the edit.
• LOW docs/concepts/pdp/overview.mdx:41: the Cloud PDP section (line 53) and the Edge PDP section (line 166) each give the SDK's PDP URL and key. The Nexus PDP section gives neither, and the page mentions the Nexus PDP API key only in the AuthZen section.

Details are in the inline comments on each line.

[EliMoshkovich]

Thanks Zeev. All six inline points are fixed (c7c6b7d, plus 267d0a1 for the code sample), and each thread has a reply and is resolved. The two outside-the-diff items:

• bulk-check.mdx (MEDIUM): the PDP prerequisite links Deploy Nexus PDP, and a new key bullet says "On Nexus PDP, use the environment's Nexus PDP API key instead." The "Combine ReBAC and ABAC checks" example now has an "ABAC needs a container PDP" note: on the Cloud PDP and Nexus PDP the ABAC item returns a deny, not an error, so only the ReBAC check can allow the edit.
• overview.mdx Nexus PDP section (LOW): a new paragraph says to set the SDK's PDP URL to the Nexus PDP authorization API (http://localhost:7766 with the Docker example in Deploy Nexus PDP) and its token to the Nexus PDP API key. It also says Nexus PDP does not accept the environment API key.

npm run build: 0 bad links, 0 bad anchors, 525/525 routes.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[zeevmoney]

Post-merge review of the changes pushed after the approval at bd3a8f7.

Review notes: 2 MEDIUM, 1 LOW. No approval or block submitted.

• MEDIUM docs/how-to/enforce-permissions/bulk-check.mdx:50: on the Cloud PDP and Nexus PDP, the ABAC item returns the ReBAC item's result, not a deny
• MEDIUM docs/how-to/enforce-permissions/check.mdx:167: the sample still fails after the URL fix, because user must be an object
• LOW docs/how-to/enforce-permissions/check.mdx:99: the deny applies to the Cloud PDP too, and only to access that an ABAC rule would grant

The previous review's items are addressed: the Cloud PDP column with the split auth rows, the Bearer/bearer sentence, the ordering paragraph, the Deploy Nexus PDP links, the Nexus PDP SDK sentence, the bulk check key bullet, and the sample URL scheme. Each cell of the AuthZen error table, the discovery exception, the scheme matching and the order of the token and body checks match the container PDP source (pdp-server in permitio/PDP) and the Cloud PDP and Nexus PDP source. The ABAC note at check.mdx:99 is only partly fixed (see the inline comment).

Outside this diff (not inline):

• MEDIUM src/sdks/bulk-check/multiple-policy-models/example.js:2: the sample under the new ABAC note calls permit.bulk([...]). The Node.js SDK has only permit.bulkCheck() (src/index.ts:206 in permitio/permit-node), which this page's SDK table and its other two samples use, so the sample throws TypeError: permit.bulk is not a function.
• LOW docs/concepts/pdp/nexus-pdp-feature-parity.mdx:61: the same deny wording as check.mdx:99.
• LOW docs/how-to/enforce-permissions/bulk-check.mdx:63 and docs/how-to/enforce-permissions/user-permissions.mdx:196: now that these pages link Deploy Nexus PDP in their prerequisites, two sections that work only on a container PDP should say so. PDP_OPA_CLIENT_QUERY_TIMEOUT is a container PDP variable; Nexus PDP uses OPA_TIMEOUT_MS (Nexus PDP configuration reference). "Get user permissions directly from OPA" needs the OPA port, which Nexus PDP doesn't expose outside the container.

Details are in the inline comments on each line.

[zeevmoney]

[MEDIUM] On the Cloud PDP and Nexus PDP, the ABAC item returns the ReBAC item's result, not a deny

Problem: The second item in the sample below sends the same user key, action and resource instance (document:${document.id}) as the first item, plus the user's tier attribute. The Cloud PDP and Nexus PDP skip ABAC rules, but they still evaluate RBAC and ReBAC for every item, and neither model reads user attributes (the Cloud PDP and Nexus PDP source is in cloud-pdp). So on both PDP types the second result always equals the first: true when a role on the document or a tenant role grants edit, false otherwise. "The ABAC item returns a deny" holds only when the first item is denied too.

A reader who tries the example on Nexus PDP and gets [true, true] would conclude that the tier rule matched. The note's conclusion (only the ReBAC check can allow the edit) is right, but the stated reason is not. "On them" also doesn't name the PDP types (STYLE_GUIDE.md: explicit names over pronouns).

Suggestion:

:::note ABAC needs a container PDP
The Cloud PDP and Nexus PDP don't evaluate ABAC policies. On the Cloud PDP and Nexus PDP, the second check runs the role-based access control (RBAC) and ReBAC rules only and ignores the `tier` attribute. Its result always equals the first check's result, so the subscription-tier rule never allows the edit. Neither PDP type returns an error for the ABAC rule. Run a container PDP for this example. See [Cloud PDP capabilities](/concepts/pdp/cloud-pdp-capabilities) and [Nexus PDP feature parity](/concepts/pdp/nexus-pdp-feature-parity#abac).
:::

[zeevmoney]

[LOW] The deny applies to the Cloud PDP too, and only to access that an ABAC rule would grant

Problem: This sentence is the wording the previous review suggested, taken from Nexus PDP feature parity. It has two gaps:

• It names only Nexus PDP. The Cloud PDP runs the same policy code (the source is in cloud-pdp): an ABAC rule never grants access there either, and the check returns false without an error. The bulk check note added in the same commit says the deny happens on both PDP types, so the two pages disagree.
• "A check against a policy that uses condition sets, user sets, or resource sets returns a deny" reads as if every check against such a policy is denied. On both PDP types, roles still grant access through RBAC and ReBAC. Only the access that a condition-set rule would grant is lost. A reader whose policy mixes roles and condition sets could conclude that Nexus PDP denies all of their checks.

Suggestion:

The Cloud PDP and Nexus PDP don't evaluate ABAC policies. On both PDP types, a rule that uses condition sets, user sets, or resource sets never grants access: a check that only such a rule allows returns `false`, not an error. Checks that a role grants still return `true`. Run a container PDP for attribute-based checks. See [Cloud PDP capabilities](/concepts/pdp/cloud-pdp-capabilities) and [Nexus PDP feature parity](/concepts/pdp/nexus-pdp-feature-parity#abac).

The warning in Nexus PDP feature parity (line 61) uses the same wording and needs the same change.

[zeevmoney]

[MEDIUM] The sample still fails after the URL fix: user must be an object

Problem: This commit makes the sample URL work, but the body on line 171 sends "user": "john@doe.me" as a string. POST /allowed expects user to be an object with a key field on every PDP type:

• Container PDP: the request type's user field is a User struct with a required key (pdp-server/src/opa_client/allowed.rs:36-38 and :91-93 in permitio/PDP). The Json extractor rejects a string there with 422.
• Cloud PDP and Nexus PDP: the handler in cloud-pdp uses the same request shape and also answers 422.

The paragraph above the sample tells readers to send it to any of the three PDP types, so everyone who copies it gets 422. john@doe.me is also not one of the sample addresses that STYLE_GUIDE.md allows.

Suggestion: In its own commit, as STYLE_GUIDE.md "Code samples" asks, change the body:

curl -X POST <your-permit-pdp-url>/allowed \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-permit-api-key>" \
  -d '{
    "user": { "key": "john@permit.io" },
    "action": "create",
    "resource": {
      "type": "document",
      "tenant": "companyA"
    },
    "context": {}
  }'