From eef8aff4a68515b28e52bf4a4b9b6a555029f7da Mon Sep 17 00:00:00 2001 From: eli Date: Wed, 30 Sep 2026 12:28:57 -0500 Subject: [PATCH 1/4] Nexus PDP: document its error responses and where it needs the Nexus PDP API key - AuthZen compatibility: scope the AuthZen error codes to the container PDP and add a table of what Nexus PDP returns instead (401 JSON message, 400, 422, 415 plain text), and that it checks the body before the token. - Get your API key, and the check, user-permissions and authorized-users how-tos: say that Nexus PDP takes the Nexus PDP API key, not the environment API key. Co-Authored-By: Claude Opus 5.5 --- docs/concepts/pdp/overview.mdx | 13 ++++++++++++- .../how-to/enforce-permissions/authorized-users.mdx | 2 +- docs/how-to/enforce-permissions/check.mdx | 4 ++-- .../how-to/enforce-permissions/user-permissions.mdx | 2 +- docs/overview/get-api-key.mdx | 4 ++++ 5 files changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/concepts/pdp/overview.mdx b/docs/concepts/pdp/overview.mdx index e719ef25..a6c42e62 100644 --- a/docs/concepts/pdp/overview.mdx +++ b/docs/concepts/pdp/overview.mdx @@ -377,7 +377,18 @@ The PDP implements the [OpenID AuthZen Authorization API 1.0](https://openid.git Every AuthZen endpoint requires the header `Authorization: Bearer `. Each AuthZen example uses two placeholders: replace `YOUR_API_KEY` with your environment API key, and `http://localhost:7766` with your PDP URL. On Nexus PDP, the bearer token is the Nexus PDP API key. -A request that omits a required field, or that carries invalid JSON such as a trailing comma before a closing brace, gets HTTP `400` with the AuthZen error code `invalid_request`. A request with a missing or wrong bearer token gets HTTP `401` with the code `unauthorized`. +On the container PDP, a request that omits a required field, or that carries invalid JSON such as a trailing comma before a closing brace, gets HTTP `400` with the AuthZen error code `invalid_request`. A request with a missing or wrong bearer token gets HTTP `401` with the code `unauthorized`. + +Nexus PDP does not return AuthZen error codes: + +| Request | Nexus PDP response | +| --- | --- | +| Missing, malformed, or wrong bearer token | HTTP `401` with the JSON body `{"message":"Unauthorized"}` | +| Body that is not valid JSON | HTTP `400` with a plain-text description | +| Body that omits a required field or gives a field the wrong type | HTTP `422` with a plain-text description | +| No `Content-Type: application/json` header | HTTP `415` with a plain-text description | + +Nexus PDP checks the request body before the bearer token, so a malformed request gets `400`, `415`, or `422` even when its token is wrong. | AuthZen operation | Method and path | Required body fields | | --- | --- | --- | diff --git a/docs/how-to/enforce-permissions/authorized-users.mdx b/docs/how-to/enforce-permissions/authorized-users.mdx index 547edfe8..cb79679b 100644 --- a/docs/how-to/enforce-permissions/authorized-users.mdx +++ b/docs/how-to/enforce-permissions/authorized-users.mdx @@ -143,7 +143,7 @@ Put `context` at the top level of the request body, next to `action` and `resour -Replace localhost:7766 with the PDP address as seen from the caller, and <api key> with your environment API key. +Replace localhost:7766 with the PDP address as seen from the caller, and <api key> with your environment API key. On Nexus PDP, use the Nexus PDP API key instead. ``` curl --location 'http://localhost:7766/authorized_users' \ diff --git a/docs/how-to/enforce-permissions/check.mdx b/docs/how-to/enforce-permissions/check.mdx index fa3259c8..d57d97f5 100644 --- a/docs/how-to/enforce-permissions/check.mdx +++ b/docs/how-to/enforce-permissions/check.mdx @@ -10,7 +10,7 @@ Call `permit.check()` from your backend to decide whether a user can perform an ## Prerequisites - A Permit.io policy with at least one resource, action, and role ([Configure your first RBAC policy](/overview/configure-your-first-rbac-policy)) -- Your environment API key ([Get your API key](/overview/get-api-key)) +- Your environment API key ([Get your API key](/overview/get-api-key)). On Nexus PDP, use the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. - A Permit SDK client connected to a PDP ([Run the PDP](/overview/run-pdp)) The examples on this page use the Node.js SDK. The other Permit SDKs take the same arguments: `permit.check()` in Python and Java, and `permit.Check()` in Go. @@ -161,7 +161,7 @@ In the Node.js SDK, the fourth argument of `permit.check()` is the context objec ## Call the PDP API directly \{#using-the-api} -Without an SDK, send the check to the PDP's `POST /allowed` endpoint. Pass your environment API key in the `Authorization: Bearer` header and the check in the JSON body. +Without an SDK, send the check to the PDP's `POST /allowed` endpoint. Pass your environment API key in the `Authorization: Bearer` header and the check in the JSON body. On Nexus PDP, pass the Nexus PDP API key instead. ```bash curl -X POST https:///allowed \ diff --git a/docs/how-to/enforce-permissions/user-permissions.mdx b/docs/how-to/enforce-permissions/user-permissions.mdx index 978675f6..59289917 100644 --- a/docs/how-to/enforce-permissions/user-permissions.mdx +++ b/docs/how-to/enforce-permissions/user-permissions.mdx @@ -139,7 +139,7 @@ The Node.js and Python SDK functions don't take a context argument. From those l -Replace `localhost:7766` with the PDP address as seen from the caller, and `` with your environment API key. +Replace `localhost:7766` with the PDP address as seen from the caller, and `` with your environment API key. On Nexus PDP, use the [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. ``` curl --location 'http://localhost:7766/user-permissions' \ diff --git a/docs/overview/get-api-key.mdx b/docs/overview/get-api-key.mdx index 1d349b58..14a1bdc5 100644 --- a/docs/overview/get-api-key.mdx +++ b/docs/overview/get-api-key.mdx @@ -8,6 +8,10 @@ import CodeBlock from "../../src/components/code-block/CodeBlock"; Copy the environment API key that your application, the Permit SDK, and your policy decision point (PDP) use to authenticate with Permit.io. Each API key belongs to one environment, so copy the key of the environment your application connects to. +:::note Nexus PDP uses its own key +Nexus PDP does not accept the environment API key. Set Nexus PDP's `PDP_API_KEY`, and the `token` of every SDK or service that queries it, to the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites). +::: + ## Prerequisites - A Permit.io account with a project and an environment. See [Projects and environments](/manage-your-account/projects-and-env). From db345d36a726e86a84d92f06b955b4c454d2167a Mon Sep 17 00:00:00 2001 From: eli Date: Wed, 30 Sep 2026 13:04:08 -0500 Subject: [PATCH 2/4] Nexus PDP docs: correct the AuthZen errors for both PDP types; key guidance in Prerequisites Review follow-ups on #661: - AuthZen errors: one table for the container PDP and Nexus PDP. The container PDP answers a wrong key with 403, a missing field with 422, and neither PDP sends AuthZen error codes. Add the /access/v1/evaluations 400 cases and 413, and say which checks run before the token on each PDP type. Discovery on Nexus PDP answers without a token. - user-permissions, authorized-users, data-filtering: the Nexus PDP key goes in Prerequisites, not the ABAC cURL examples; the ABAC notes name Nexus PDP. - check: link Deploy Nexus PDP next to Run the PDP, and give the Nexus PDP URL. - First mention on each page is a linked "Permit Nexus PDP". Co-Authored-By: Claude Opus 5.5 --- docs/concepts/pdp/overview.mdx | 26 ++++++++++--------- .../enforce-permissions/authorized-users.mdx | 5 ++-- docs/how-to/enforce-permissions/check.mdx | 8 +++--- .../enforce-permissions/data-filtering.mdx | 4 +-- .../enforce-permissions/user-permissions.mdx | 5 ++-- docs/overview/get-api-key.mdx | 4 +-- 6 files changed, 28 insertions(+), 24 deletions(-) diff --git a/docs/concepts/pdp/overview.mdx b/docs/concepts/pdp/overview.mdx index a6c42e62..fa641037 100644 --- a/docs/concepts/pdp/overview.mdx +++ b/docs/concepts/pdp/overview.mdx @@ -375,20 +375,22 @@ To turn on caching and set the TTL, see [Cache configuration](/concepts/pdp/conf The PDP implements the [OpenID AuthZen Authorization API 1.0](https://openid.github.io/authzen/), a standard API between policy enforcement points (PEPs) and PDPs. Any AuthZen client can send authorization requests to a Permit PDP. -Every AuthZen endpoint requires the header `Authorization: Bearer `. Each AuthZen example uses two placeholders: replace `YOUR_API_KEY` with your environment API key, and `http://localhost:7766` with your PDP URL. On Nexus PDP, the bearer token is the Nexus PDP API key. +The container PDP requires the header `Authorization: Bearer ` on every AuthZen endpoint. Nexus PDP requires it on every AuthZen endpoint except discovery (`GET /.well-known/authzen-configuration`), which answers without a token. Each AuthZen example uses two placeholders: replace `YOUR_API_KEY` with your environment API key, and `http://localhost:7766` with your PDP URL. On Nexus PDP, the bearer token is the Nexus PDP API key. -On the container PDP, a request that omits a required field, or that carries invalid JSON such as a trailing comma before a closing brace, gets HTTP `400` with the AuthZen error code `invalid_request`. A request with a missing or wrong bearer token gets HTTP `401` with the code `unauthorized`. +AuthZen error responses carry an HTTP status and a description, not an AuthZen error code. The status depends on the PDP type: -Nexus PDP does not return AuthZen error codes: - -| Request | Nexus PDP response | -| --- | --- | -| Missing, malformed, or wrong bearer token | HTTP `401` with the JSON body `{"message":"Unauthorized"}` | -| Body that is not valid JSON | HTTP `400` with a plain-text description | -| Body that omits a required field or gives a field the wrong type | HTTP `422` with a plain-text description | -| No `Content-Type: application/json` header | HTTP `415` with a plain-text description | - -Nexus PDP checks the request body before the bearer token, so a malformed request gets `400`, `415`, or `422` even when its token is wrong. +| Request | Container PDP | Nexus PDP | +| --- | --- | --- | +| No `Authorization` header | `401`, plain text | `401`, JSON body `{"message":"Unauthorized"}` | +| Wrong API key, or a header without the `Bearer` scheme | `403`, plain text | `401`, JSON body `{"message":"Unauthorized"}` | +| Body that is not valid JSON | `400`, plain text | `400`, plain text | +| Body that omits a required field or gives a field the wrong type | `422`, plain text | `422`, plain text | +| No `Content-Type: application/json` header | `415`, plain text | `415`, plain text | +| Body larger than 2 MB | `413`, plain text | `413`, plain text | +| `/access/v1/evaluations` item without `subject`, `action`, or `resource`, and no top-level value for it | `400`, plain text | `400`, plain text | +| `/access/v1/evaluations` with an empty `evaluations` array | `400`, plain text | `400`, JSON body `{"evaluations":[]}` | + +The container PDP checks the bearer token before it reads the body, so a request with a wrong token gets `401` or `403` whatever its body. Nexus PDP parses the request body before it checks the bearer token, so a body that is not valid JSON, lacks a required field, has no JSON `Content-Type`, or is larger than 2 MB gets `400`, `422`, `415`, or `413` even when its token is wrong. The `/access/v1/evaluations` item checks run after the token check. | AuthZen operation | Method and path | Required body fields | | --- | --- | --- | diff --git a/docs/how-to/enforce-permissions/authorized-users.mdx b/docs/how-to/enforce-permissions/authorized-users.mdx index cb79679b..0cff9ccd 100644 --- a/docs/how-to/enforce-permissions/authorized-users.mdx +++ b/docs/how-to/enforce-permissions/authorized-users.mdx @@ -13,6 +13,7 @@ List the users who can perform an action on a resource type or a resource instan ## Prerequisites - The Python SDK connected to a policy decision point (PDP) version 0.4.0 or later ([Run the PDP](/overview/run-pdp)) +- Your environment API key ([Get your API key](/overview/get-api-key)). On [Permit Nexus PDP](/concepts/pdp/nexus-pdp), use the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. - Users with role assignments in Permit ([Sync users](/how-to/sync-users)) `permit.authorized_users()` is an asynchronous function of the Python SDK client (`from permit import Permit`). Call it with `await`. From other languages, call the PDP's `POST /authorized_users` endpoint. @@ -136,14 +137,14 @@ When a user also has access through a tenant-level role, the user's list contain By default, the result includes only users with role assignments that grant the action. To also include users granted access by attribute-based access control (ABAC) rules, set `enable_abac_authorized_users` to `true` in the request context. :::warning ABAC evaluation is slower -ABAC evaluation in authorized users queries is performance-intensive, so it is off by default. Set `enable_abac_authorized_users` only on the requests that need ABAC results. ABAC also needs a container PDP, because the Cloud PDP doesn't evaluate ABAC policies ([Cloud PDP capabilities](/concepts/pdp/cloud-pdp-capabilities)). +ABAC evaluation in authorized users queries is performance-intensive, so it is off by default. Set `enable_abac_authorized_users` only on the requests that need ABAC results. ABAC also needs a container PDP, because the Cloud PDP and Nexus PDP don't evaluate ABAC policies ([Cloud PDP capabilities](/concepts/pdp/cloud-pdp-capabilities), [Nexus PDP feature parity](/concepts/pdp/nexus-pdp-feature-parity#abac)). ::: Put `context` at the top level of the request body, next to `action` and `resource`. -Replace localhost:7766 with the PDP address as seen from the caller, and <api key> with your environment API key. On Nexus PDP, use the Nexus PDP API key instead. +Replace localhost:7766 with the PDP address as seen from the caller, and <api key> with your environment API key. ``` curl --location 'http://localhost:7766/authorized_users' \ diff --git a/docs/how-to/enforce-permissions/check.mdx b/docs/how-to/enforce-permissions/check.mdx index d57d97f5..d9b73213 100644 --- a/docs/how-to/enforce-permissions/check.mdx +++ b/docs/how-to/enforce-permissions/check.mdx @@ -10,8 +10,8 @@ Call `permit.check()` from your backend to decide whether a user can perform an ## Prerequisites - A Permit.io policy with at least one resource, action, and role ([Configure your first RBAC policy](/overview/configure-your-first-rbac-policy)) -- Your environment API key ([Get your API key](/overview/get-api-key)). On Nexus PDP, use the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. -- A Permit SDK client connected to a PDP ([Run the PDP](/overview/run-pdp)) +- Your environment API key ([Get your API key](/overview/get-api-key)). On [Permit Nexus PDP](/concepts/pdp/nexus-pdp), use the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. +- A Permit SDK client connected to a PDP ([Run the PDP](/overview/run-pdp), or [Deploy Nexus PDP](/concepts/pdp/nexus-pdp-deployment) for Nexus PDP) The examples on this page use the Node.js SDK. The other Permit SDKs take the same arguments: `permit.check()` in Python and Java, and `permit.Check()` in Go. @@ -96,7 +96,7 @@ const permitted = await permit.check( ``` :::note ABAC needs a container PDP -The Cloud PDP doesn't evaluate ABAC policies. Run a container PDP for attribute-based checks. See [Cloud PDP capabilities](/concepts/pdp/cloud-pdp-capabilities). +The Cloud PDP and Nexus PDP don't evaluate ABAC policies. 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). ::: To store attributes in Permit instead of passing them on every check, see [Load custom data](/how-to/manage-data/loading-data). @@ -178,7 +178,7 @@ curl -X POST https:///allowed \ }' ``` -Replace `` with the address of your container PDP (for example, `http://localhost:7766`) or the Cloud PDP (`https://cloudpdp.api.permit.io`). +Replace `` with the address of your container PDP (for example, `http://localhost:7766`) or the Cloud PDP (`https://cloudpdp.api.permit.io`). For Nexus PDP, use the address of its authorization API ([Deploy Nexus PDP](/concepts/pdp/nexus-pdp-deployment)). The response body contains an `allow` field. `"allow": true` means the user is permitted. diff --git a/docs/how-to/enforce-permissions/data-filtering.mdx b/docs/how-to/enforce-permissions/data-filtering.mdx index 415c9383..7ce90e6d 100644 --- a/docs/how-to/enforce-permissions/data-filtering.mdx +++ b/docs/how-to/enforce-permissions/data-filtering.mdx @@ -14,13 +14,13 @@ Return only the data a user is allowed to see, instead of a single allow or deny - A Permit SDK client connected to a policy decision point (PDP) ([Run the PDP](/overview/run-pdp)) - A policy with resource instances or attributes that decide which records a user can access -- Your environment API key ([Get your API key](/overview/get-api-key)) +- Your environment API key ([Get your API key](/overview/get-api-key)). On [Permit Nexus PDP](/concepts/pdp/nexus-pdp), use the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. ## Filter a list of objects with the SDK \{#pdp-level-filtering} `FilterObjects()` in Go and `filter_objects()` in Python take a user, an action, a request context, and the resources to filter. Both send one bulk check to the PDP and return the resources the user can perform the action on, in the order you passed them. Resources the policy denies are left out of the returned list, so the returned list is usually shorter than the list you passed. -In both samples, replace `` with your environment API key, and replace the `document` and `folder` resources with resources from your own policy. +In both samples, replace `` with your environment API key (the Nexus PDP API key on Nexus PDP), and replace the `document` and `folder` resources with resources from your own policy. diff --git a/docs/how-to/enforce-permissions/user-permissions.mdx b/docs/how-to/enforce-permissions/user-permissions.mdx index 59289917..6d1955d9 100644 --- a/docs/how-to/enforce-permissions/user-permissions.mdx +++ b/docs/how-to/enforce-permissions/user-permissions.mdx @@ -13,6 +13,7 @@ Get every permission a user has, in every tenant and on every resource instance, ## Prerequisites - A Permit SDK client connected to a PDP ([Run the PDP](/overview/run-pdp)) +- Your environment API key ([Get your API key](/overview/get-api-key)). On [Permit Nexus PDP](/concepts/pdp/nexus-pdp), use the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. - Users with role assignments in Permit ([Sync users](/how-to/sync-users)) ## Get user permissions function by SDK @@ -132,14 +133,14 @@ When you enable ABAC permissions: - Pass `resource_types`. The PDP needs the resource types to evaluate ABAC rules. - Add `__tenant` to `resource_types` to keep tenant-level (RBAC) permissions in the result. -- Run a container PDP. The Cloud PDP doesn't evaluate ABAC policies ([Cloud PDP capabilities](/concepts/pdp/cloud-pdp-capabilities)). +- Run a container PDP. The Cloud PDP and Nexus PDP don't evaluate ABAC policies ([Cloud PDP capabilities](/concepts/pdp/cloud-pdp-capabilities), [Nexus PDP feature parity](/concepts/pdp/nexus-pdp-feature-parity#abac)). The Node.js and Python SDK functions don't take a context argument. From those languages, call the PDP API directly. -Replace `localhost:7766` with the PDP address as seen from the caller, and `` with your environment API key. On Nexus PDP, use the [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. +Replace `localhost:7766` with the PDP address as seen from the caller, and `` with your environment API key. ``` curl --location 'http://localhost:7766/user-permissions' \ diff --git a/docs/overview/get-api-key.mdx b/docs/overview/get-api-key.mdx index 14a1bdc5..515565d4 100644 --- a/docs/overview/get-api-key.mdx +++ b/docs/overview/get-api-key.mdx @@ -8,8 +8,8 @@ import CodeBlock from "../../src/components/code-block/CodeBlock"; Copy the environment API key that your application, the Permit SDK, and your policy decision point (PDP) use to authenticate with Permit.io. Each API key belongs to one environment, so copy the key of the environment your application connects to. -:::note Nexus PDP uses its own key -Nexus PDP does not accept the environment API key. Set Nexus PDP's `PDP_API_KEY`, and the `token` of every SDK or service that queries it, to the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites). +:::note Permit Nexus PDP uses its own key +[Permit Nexus PDP](/concepts/pdp/nexus-pdp) does not accept the environment API key. Set Nexus PDP's `PDP_API_KEY`, and the `token` of every SDK or service that queries it, to the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites). ::: ## Prerequisites From c7c6b7d69172dcb967504d3f78e522960ce33d9b Mon Sep 17 00:00:00 2001 From: eli Date: Wed, 30 Sep 2026 13:35:31 -0500 Subject: [PATCH 3/4] Nexus PDP docs: add the Cloud PDP to the AuthZen errors; Nexus setup and ABAC notes Review follow-ups on #661 (approved round): - AuthZen errors: a Cloud PDP column (verified against cloudpdp.api.permit.io), split the no-scheme and wrong-key rows, note that Nexus PDP and the Cloud PDP match only `Bearer`/`bearer`, link the Cloud PDP 429, and say which checks run before the token on each PDP type, including a missing token and the empty `evaluations` array. - Nexus PDP section of the overview: how to point an SDK at Nexus PDP and which key it takes. - user-permissions, authorized-users, data-filtering, bulk-check: link Deploy Nexus PDP in the PDP prerequisite; bulk-check gets the key bullet. - ABAC notes in check and bulk-check say an ABAC check on Nexus PDP returns a deny, not an error. Co-Authored-By: Claude Opus 5.5 --- docs/concepts/pdp/overview.mdx | 31 +++++++++++-------- .../enforce-permissions/authorized-users.mdx | 4 +-- .../how-to/enforce-permissions/bulk-check.mdx | 7 ++++- docs/how-to/enforce-permissions/check.mdx | 2 +- .../enforce-permissions/data-filtering.mdx | 4 +-- .../enforce-permissions/user-permissions.mdx | 4 +-- 6 files changed, 31 insertions(+), 21 deletions(-) diff --git a/docs/concepts/pdp/overview.mdx b/docs/concepts/pdp/overview.mdx index fa641037..e594b8f8 100644 --- a/docs/concepts/pdp/overview.mdx +++ b/docs/concepts/pdp/overview.mdx @@ -40,6 +40,8 @@ Nexus PDP differs from the Edge PDP in four ways: Nexus PDP supports RBAC, ReBAC with role derivation, and multi-tenancy through the same check, bulk check, user permissions, authorized users, and AuthZen endpoints as the Edge PDP. Its capabilities match the managed Cloud PDP, running in your network. ABAC, policy as code, local facts, URL-based enforcement, and custom data sources require the Edge PDP. Both PDP types connect to the same Permit environment, so you can run them side by side. For the full comparison, see [Nexus PDP feature parity](/concepts/pdp/nexus-pdp-feature-parity). +To connect an SDK to Nexus PDP, set the PDP URL to the address of its authorization API (`http://localhost:7766` with the Docker example in [Deploy Nexus PDP](/concepts/pdp/nexus-pdp-deployment)) and the SDK's `token` to the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites). Nexus PDP does not accept the environment API key. + :::info Nexus PDP availability As of September 2026, Nexus PDP is in early access and Permit enables it per account. To request access, [book a call with Permit](https://www.permit.io/demo). ::: @@ -375,22 +377,25 @@ To turn on caching and set the TTL, see [Cache configuration](/concepts/pdp/conf The PDP implements the [OpenID AuthZen Authorization API 1.0](https://openid.github.io/authzen/), a standard API between policy enforcement points (PEPs) and PDPs. Any AuthZen client can send authorization requests to a Permit PDP. -The container PDP requires the header `Authorization: Bearer ` on every AuthZen endpoint. Nexus PDP requires it on every AuthZen endpoint except discovery (`GET /.well-known/authzen-configuration`), which answers without a token. Each AuthZen example uses two placeholders: replace `YOUR_API_KEY` with your environment API key, and `http://localhost:7766` with your PDP URL. On Nexus PDP, the bearer token is the Nexus PDP API key. +The container PDP requires the header `Authorization: Bearer ` on every AuthZen endpoint. Nexus PDP and the Cloud PDP require it on every AuthZen endpoint except discovery (`GET /.well-known/authzen-configuration`), which answers without a token. Each AuthZen example uses two placeholders: replace `YOUR_API_KEY` with your environment API key, and `http://localhost:7766` with your PDP URL. On Nexus PDP, the bearer token is the Nexus PDP API key. AuthZen error responses carry an HTTP status and a description, not an AuthZen error code. The status depends on the PDP type: -| Request | Container PDP | Nexus PDP | -| --- | --- | --- | -| No `Authorization` header | `401`, plain text | `401`, JSON body `{"message":"Unauthorized"}` | -| Wrong API key, or a header without the `Bearer` scheme | `403`, plain text | `401`, JSON body `{"message":"Unauthorized"}` | -| Body that is not valid JSON | `400`, plain text | `400`, plain text | -| Body that omits a required field or gives a field the wrong type | `422`, plain text | `422`, plain text | -| No `Content-Type: application/json` header | `415`, plain text | `415`, plain text | -| Body larger than 2 MB | `413`, plain text | `413`, plain text | -| `/access/v1/evaluations` item without `subject`, `action`, or `resource`, and no top-level value for it | `400`, plain text | `400`, plain text | -| `/access/v1/evaluations` with an empty `evaluations` array | `400`, plain text | `400`, JSON body `{"evaluations":[]}` | - -The container PDP checks the bearer token before it reads the body, so a request with a wrong token gets `401` or `403` whatever its body. Nexus PDP parses the request body before it checks the bearer token, so a body that is not valid JSON, lacks a required field, has no JSON `Content-Type`, or is larger than 2 MB gets `400`, `422`, `415`, or `413` even when its token is wrong. The `/access/v1/evaluations` item checks run after the token check. +| Request | Container PDP | Nexus PDP | Cloud PDP | +| --- | --- | --- | --- | +| No `Authorization` header | `401`, plain text | `401`, JSON body `{"message":"Unauthorized"}` | `401`, JSON body `{"message":"Unauthorized"}` | +| A header without the `Bearer` scheme | `403`, plain text | `401`, JSON body `{"message":"Unauthorized"}` | `401`, JSON body `{"message":"Unauthorized"}` | +| Wrong API key | `403`, plain text | `401`, JSON body `{"message":"Unauthorized"}` | `403`, JSON body `{"message":"Forbidden"}` | +| Body that is not valid JSON | `400`, plain text | `400`, plain text | `400`, plain text | +| Body that omits a required field or gives a field the wrong type | `422`, plain text | `422`, plain text | `422`, plain text | +| No `Content-Type: application/json` header | `415`, plain text | `415`, plain text | `415`, plain text | +| Body larger than 2 MB | `413`, plain text | `413`, plain text | `413`, plain text | +| `/access/v1/evaluations` item without `subject`, `action`, or `resource`, and no top-level value for it | `400`, plain text | `400`, plain text | `400`, plain text | +| `/access/v1/evaluations` with an empty `evaluations` array | `400`, plain text | `400`, JSON body `{"evaluations":[]}` | `400`, JSON body `{"evaluations":[]}` | + +Nexus PDP and the Cloud PDP accept the scheme only as `Bearer` or `bearer`. Any other capitalization, such as `BEARER`, gets `401` even with the right API key. The container PDP accepts any capitalization. The Cloud PDP also answers requests over its rate limit with `429`; see [Cloud PDP rate limits](/concepts/pdp/cloud-pdp-capabilities#rate-limits). + +The container PDP checks the bearer token before it reads the body, so a request with a missing or wrong token gets `401` or `403` whatever its body. Nexus PDP and the Cloud PDP parse the request body before they check the bearer token, so a body that is not valid JSON, lacks a required field, has no JSON `Content-Type`, or is larger than 2 MB gets `400`, `422`, `415`, or `413` even when the token is missing or wrong. On every PDP type, the `/access/v1/evaluations` checks for an empty `evaluations` array and for items without `subject`, `action`, or `resource` run after the token check, so those requests get the token error when the token is missing or wrong. | AuthZen operation | Method and path | Required body fields | | --- | --- | --- | diff --git a/docs/how-to/enforce-permissions/authorized-users.mdx b/docs/how-to/enforce-permissions/authorized-users.mdx index 0cff9ccd..7f91c280 100644 --- a/docs/how-to/enforce-permissions/authorized-users.mdx +++ b/docs/how-to/enforce-permissions/authorized-users.mdx @@ -12,8 +12,8 @@ List the users who can perform an action on a resource type or a resource instan ## Prerequisites -- The Python SDK connected to a policy decision point (PDP) version 0.4.0 or later ([Run the PDP](/overview/run-pdp)) -- Your environment API key ([Get your API key](/overview/get-api-key)). On [Permit Nexus PDP](/concepts/pdp/nexus-pdp), use the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. +- The Python SDK connected to a policy decision point (PDP) version 0.4.0 or later ([Run the PDP](/overview/run-pdp), or [Deploy Nexus PDP](/concepts/pdp/nexus-pdp-deployment) for [Permit Nexus PDP](/concepts/pdp/nexus-pdp)) +- Your environment API key ([Get your API key](/overview/get-api-key)). On Nexus PDP, use the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. - Users with role assignments in Permit ([Sync users](/how-to/sync-users)) `permit.authorized_users()` is an asynchronous function of the Python SDK client (`from permit import Permit`). Call it with `await`. From other languages, call the PDP's `POST /authorized_users` endpoint. diff --git a/docs/how-to/enforce-permissions/bulk-check.mdx b/docs/how-to/enforce-permissions/bulk-check.mdx index 7c5cdadf..1da97cad 100644 --- a/docs/how-to/enforce-permissions/bulk-check.mdx +++ b/docs/how-to/enforce-permissions/bulk-check.mdx @@ -11,7 +11,8 @@ Send several permission checks to the policy decision point (PDP) in one request ## Prerequisites -- A Permit SDK client connected to a PDP ([Run the PDP](/overview/run-pdp)) +- A Permit SDK client connected to a PDP ([Run the PDP](/overview/run-pdp), or [Deploy Nexus PDP](/concepts/pdp/nexus-pdp-deployment) for [Permit Nexus PDP](/concepts/pdp/nexus-pdp)) +- Your environment API key ([Get your API key](/overview/get-api-key)). On Nexus PDP, use the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. - Familiarity with the arguments of [`permit.check()`](/how-to/enforce-permissions/check) ## Run a bulk check @@ -45,6 +46,10 @@ When one API endpoint performs several actions, send all the checks in one bulk Some operations depend on two policy models. In this example, a user can `edit` a document when a relationship-based access control (ReBAC) role on the document grants `edit`, or when an attribute-based access control (ABAC) rule grants `edit` to the user's subscription tier. The bulk check sends both checks at once, and the code allows the edit when either result is `true`. +:::note ABAC needs a container PDP +The Cloud PDP and Nexus PDP don't evaluate ABAC policies. On them, the ABAC item returns a deny, not an error, so only the ReBAC check can allow the edit. 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). +::: + ### Filter a list of resources \{#data-filtering} diff --git a/docs/how-to/enforce-permissions/check.mdx b/docs/how-to/enforce-permissions/check.mdx index d9b73213..2f4195b4 100644 --- a/docs/how-to/enforce-permissions/check.mdx +++ b/docs/how-to/enforce-permissions/check.mdx @@ -96,7 +96,7 @@ const permitted = await permit.check( ``` :::note ABAC needs a container PDP -The Cloud PDP and Nexus PDP don't evaluate ABAC policies. 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 Cloud PDP and Nexus PDP don't evaluate ABAC policies. On Nexus PDP, a check against a policy that uses condition sets, user sets, or resource sets returns a deny, not an error. 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). ::: To store attributes in Permit instead of passing them on every check, see [Load custom data](/how-to/manage-data/loading-data). diff --git a/docs/how-to/enforce-permissions/data-filtering.mdx b/docs/how-to/enforce-permissions/data-filtering.mdx index 7ce90e6d..6c45b3a8 100644 --- a/docs/how-to/enforce-permissions/data-filtering.mdx +++ b/docs/how-to/enforce-permissions/data-filtering.mdx @@ -12,9 +12,9 @@ Return only the data a user is allowed to see, instead of a single allow or deny ## Prerequisites -- A Permit SDK client connected to a policy decision point (PDP) ([Run the PDP](/overview/run-pdp)) +- A Permit SDK client connected to a policy decision point (PDP) ([Run the PDP](/overview/run-pdp), or [Deploy Nexus PDP](/concepts/pdp/nexus-pdp-deployment) for [Permit Nexus PDP](/concepts/pdp/nexus-pdp)) - A policy with resource instances or attributes that decide which records a user can access -- Your environment API key ([Get your API key](/overview/get-api-key)). On [Permit Nexus PDP](/concepts/pdp/nexus-pdp), use the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. +- Your environment API key ([Get your API key](/overview/get-api-key)). On Nexus PDP, use the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. ## Filter a list of objects with the SDK \{#pdp-level-filtering} diff --git a/docs/how-to/enforce-permissions/user-permissions.mdx b/docs/how-to/enforce-permissions/user-permissions.mdx index 6d1955d9..91dd51b4 100644 --- a/docs/how-to/enforce-permissions/user-permissions.mdx +++ b/docs/how-to/enforce-permissions/user-permissions.mdx @@ -12,8 +12,8 @@ Get every permission a user has, in every tenant and on every resource instance, ## Prerequisites -- A Permit SDK client connected to a PDP ([Run the PDP](/overview/run-pdp)) -- Your environment API key ([Get your API key](/overview/get-api-key)). On [Permit Nexus PDP](/concepts/pdp/nexus-pdp), use the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. +- A Permit SDK client connected to a PDP ([Run the PDP](/overview/run-pdp), or [Deploy Nexus PDP](/concepts/pdp/nexus-pdp-deployment) for [Permit Nexus PDP](/concepts/pdp/nexus-pdp)) +- Your environment API key ([Get your API key](/overview/get-api-key)). On Nexus PDP, use the environment's [Nexus PDP API key](/concepts/pdp/nexus-pdp-deployment#prerequisites) instead. - Users with role assignments in Permit ([Sync users](/how-to/sync-users)) ## Get user permissions function by SDK From 267d0a15c686c972337d104226a48ad431d9d6b5 Mon Sep 17 00:00:00 2001 From: eli Date: Wed, 30 Sep 2026 13:35:31 -0500 Subject: [PATCH 4/4] check: drop the scheme from the POST /allowed sample URL The addresses to substitute already include one, so following the page gave https://http://localhost:7766/allowed. Co-Authored-By: Claude Opus 5.5 --- docs/how-to/enforce-permissions/check.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/enforce-permissions/check.mdx b/docs/how-to/enforce-permissions/check.mdx index 2f4195b4..847c1c49 100644 --- a/docs/how-to/enforce-permissions/check.mdx +++ b/docs/how-to/enforce-permissions/check.mdx @@ -164,7 +164,7 @@ In the Node.js SDK, the fourth argument of `permit.check()` is the context objec Without an SDK, send the check to the PDP's `POST /allowed` endpoint. Pass your environment API key in the `Authorization: Bearer` header and the check in the JSON body. On Nexus PDP, pass the Nexus PDP API key instead. ```bash -curl -X POST https:///allowed \ +curl -X POST /allowed \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{