List the users authorized on a resource
List the users who can perform an action on a resource type or a resource instance, together with the role assignments that grant each user access. This page is for developers who need to answer "who can do X on Y?", for example to show the people with access to a document.
Prerequisites
- The Python SDK connected to a policy decision point (PDP) version 0.4.0 or later (Run the PDP, or Deploy Nexus PDP for Permit Nexus PDP)
- Your environment API key (Get your API key). On Nexus PDP, use the environment's Nexus PDP API key instead.
- Users with role assignments in Permit (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.
Function arguments
| Argument | Type | Required | Description |
|---|---|---|---|
action | str | Yes | The action to check, for example read. |
resource | str or dict | Yes | A resource type (repo), a resource instance (repo:OPAL), or a dict with type, optional key, optional tenant, and optional attributes. |
context | dict | No | Extra data for the policy evaluation, such as the ABAC flag described in Include ABAC rules. |
List the users authorized on a resource type
This example lists the users who can read any repo:
- Python
from permit import AuthorizedUsersResult
authorized_users: AuthorizedUsersResult = await permit.authorized_users(
"read", "repo",
)
The result has this shape:
{
"resource": "repo:*",
"tenant": "default",
"users": {
"user1": [
{
"user": "user1",
"tenant": "default",
"resource": "__tenant:default",
"role": "admin"
}
]
}
}
Read the authorized users result
| Field | Description |
|---|---|
resource | The resource the result is about: type:* for a resource type, or type:key for a resource instance. |
tenant | The tenant the result is about. |
users | An object keyed by user key. Each value is the list of role assignments that grant the user the action. |
Each role assignment has user, tenant, resource, and role. A resource value of __tenant:<tenant_key> means a tenant-level role grants the access.
List the users authorized on a resource instance
Pass a resource instance in type:key format, the same format as in permit.check(). The result lists the users who can perform the action on that instance.
- Python
from permit import AuthorizedUsersResult
authorized_users: AuthorizedUsersResult = await permit.authorized_users(
"read", "repo:OPAL",
)
The result has this shape:
{
"resource": "repo:OPAL",
"tenant": "default",
"users": {
"user1": [
{
"user": "user1",
"tenant": "default",
"resource": "repo:OPAL",
"role": "admin"
}
]
}
}
When a user also has access through a tenant-level role, the user's list contains both role assignments:
{
"resource": "repo:OPAL",
"tenant": "default",
"users": {
"user1": [
{
"user": "user1",
"tenant": "default",
"resource": "repo:OPAL",
"role": "admin"
},
{
"user": "user1",
"tenant": "default",
"resource": "__tenant:default",
"role": "admin"
}
]
}
}
Include ABAC rules in the result
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.
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, Nexus PDP feature parity).
Put context at the top level of the request body, next to action and resource.
- cURL
- Python
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' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <api key>' \
--data '{
"action": "read",
"resource": {
"type": "Document",
"tenant": "default",
"attributes": {
"cost": 500,
"create_at": 2026
}
},
"context": {
"enable_abac_authorized_users": true
}
}'
from permit import AuthorizedUsersResult
authorized_users: AuthorizedUsersResult = await permit.authorized_users(
"read",
{
"type": "Document",
"attributes": {
"cost": 500,
"create_at": 2026,
},
},
{"enable_abac_authorized_users": True},
)