The Permission Service provides a diagnostics endpoint that allows inspecting which policies would be evaluated for a given authorization request, without actually returning a decision.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this section are to be interpreted as described in RFC 2119.
POST /v1beta/diagnostics/authorize/
POST /v1beta/diagnostics/authorize/ HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json
{
"principal": <a valid JSON object with "sub" field>,
"action": <a valid JSON object with "name" and "service" fields>,
"resource": <a valid JSON object with "id", "type" and "data" fields>,
"context": <any valid JSON object>
}
This API is a diagnostics variant of POST /v1beta/authorization/ that returns the list of policies that would be evaluated for the given PARC parameters and the evaluation priority that would be applied, instead of returning a decision. For how those policies and the priority combine into a decision in a real authorization call, see How authorization requests are evaluated.
The request body is the same as POST /v1beta/authorization/.
The access token passed in the Authorization header MUST be a valid token received from the Identity Provider (either a user or service ID token).
The caller MUST have the permissions:diagnostics permission to use this endpoint. This permission check is always performed, even when the principal in the request matches the caller.
Policies are returned in the same order they would be evaluated: sorted by order ascending, then by id ascending.
Flow
The client sends a POST /v1beta/diagnostics/authorize/ request.
The service checks that the caller has the permissions:diagnostics permission. If denied, returns 403 Forbidden.
The service looks up the evaluation priority from metadata storage.
The service fetches matching policies from policy storage.
The service returns 200 with the evaluation priority and the ordered list of policies.
Request example
POST /v1beta/diagnostics/authorize/ HTTP/1.1
Authorization: Bearer eyJraWQiOiJvYXV0aC1zaWduL[...]cc5IgUXhY66ML-CZVlRw
Content-Type: application/json
{
"principal": {"sub": "DdxA9xDiqdUbv", "email": "user@test.com", "exp": 1727821346329},
"action": {
"name": "read",
"service": "storage"
},
"resource": {
"id": "/Projects/Scene.usd",
"type": "File",
"data": {
"resourceIdentity": "/Projects/Scene.usd",
"metadata": {
"size": 1024
}
}
}
}
Response
The success response returns 200 HTTP status with the evaluation priority and the ordered list of matching policies:
HTTP/1.1 200 OK
Content-Type: application/json
{
"evaluation_priority": "forbid",
"policies": [
{
"id": 1,
"order": 0,
"policy": "permit(principal, action == Action::\"storage:read\", resource);",
"action": {"name": "read", "service": "storage"}
},
{
"id": 5,
"order": 10,
"policy": "forbid(principal == User::\"DdxA9xDiqdUbv\", action, resource);",
"principal": {"sub": "DdxA9xDiqdUbv"},
"resource": {"id": "/Projects/Scene.usd", "type": "File", "data": {}}
}
]
}
Each policy in the response includes:
The evaluation_priority field indicates the priority configured in the resource type metadata. Possible values are "forbid" (default) and "permit".
Error conditions
The following error conditions are defined:
Missing, invalid, or expired bearer or principal token
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"detail": "The principal token is expired."
}
The caller does not have the permissions:diagnostics permission
HTTP/1.1 403 Forbidden
Content-Type: application/json
The request body is invalid (missing required fields or fields represented in a wrong format)
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json
{
"detail": "'action' field is required."
}
