diff --git a/docs/concepts/pdp/overview.mdx b/docs/concepts/pdp/overview.mdx index e719ef25..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,9 +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. -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 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 | 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). -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`. +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 547edfe8..7f91c280 100644 --- a/docs/how-to/enforce-permissions/authorized-users.mdx +++ b/docs/how-to/enforce-permissions/authorized-users.mdx @@ -12,7 +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)) +- 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. @@ -136,7 +137,7 @@ 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`. 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 fa3259c8..847c1c49 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)) -- 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. 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). @@ -161,10 +161,10 @@ 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 \ +curl -X POST /allowed \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ @@ -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..6c45b3a8 100644 --- a/docs/how-to/enforce-permissions/data-filtering.mdx +++ b/docs/how-to/enforce-permissions/data-filtering.mdx @@ -12,15 +12,15 @@ 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)) +- 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} `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 978675f6..91dd51b4 100644 --- a/docs/how-to/enforce-permissions/user-permissions.mdx +++ b/docs/how-to/enforce-permissions/user-permissions.mdx @@ -12,7 +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)) +- 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 @@ -132,7 +133,7 @@ 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. diff --git a/docs/overview/get-api-key.mdx b/docs/overview/get-api-key.mdx index 1d349b58..515565d4 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 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 - A Permit.io account with a project and an environment. See [Projects and environments](/manage-your-account/projects-and-env).