Permissions API
Authorization check endpoints and permission management. YorAuth uses a resource:action permission model where wildcards are supported (posts:*, *:read, *:*).
Permission checks are cached in Redis with a 1-hour TTL and invalidated automatically when role or permission assignments change.
Authentication
All endpoints require a valid JWT access token:
Authorization: Bearer {access_token}
Check Permission
GET /api/v1/applications/{applicationId}/authz/check
POST /api/v1/applications/{applicationId}/authz/check
Check whether a user has a specific permission. Use GET for simple RBAC checks or POST when passing resource and context attributes for ABAC policy evaluation.
Authentication
Requires jwt.permission:authz:check.
Parameters (GET — query string, or POST — request body)
| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | Yes | The user to check |
permission | string | Yes | Permission in resource:action format (e.g., posts:read, users:*) |
resource | object | No | Resource attributes for ABAC evaluation (e.g., {"owner_id": "user_123"}) |
context | object | No | Request context for ABAC evaluation (e.g., {"ip": "1.2.3.4", "time": "09:00"}) |
Response — RBAC only
200 OK
{
"allowed": true,
"permission": "posts:read",
"cached": true
}
Response — With ABAC evaluation
200 OK
{
"allowed": true,
"permission": "posts:update",
"cached": false,
"abac_evaluated": true,
"policies_checked": 2
}
Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_INVALID_FORMAT | Permission does not match resource:action format |
Bulk Check Permissions
POST /api/v1/applications/{applicationId}/authz/check-bulk
Check multiple permissions for a user in a single request. Returns a result for each permission. Supports up to 50 permissions per request.
Authentication
Requires jwt.permission:authz:check.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | Yes | The user to check |
permissions | array of strings | Yes | 1–50 permissions in resource:action format |
resource | object | No | Resource attributes for ABAC evaluation |
context | object | No | Request context for ABAC evaluation |
Response
200 OK
{
"user_id": "550e8400-e29b-41d4-a716-446655440000",
"results": {
"posts:read": true,
"posts:create": true,
"posts:delete": false,
"users:read": false
}
}
Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_INVALID_FORMAT | One or more permissions are malformed |
Permissions are defined inline when creating or updating roles — there is no separate endpoint to create a standalone permission. A permission is automatically created the first time it appears in a role definition. Use the Roles API to manage permission assignments to roles.
Permission Format
Permissions follow the resource:action pattern. Both parts support the * wildcard:
| Permission | Meaning |
|---|---|
posts:read | Read posts only |
posts:* | All actions on posts |
*:read | Read access on all resources |
*:* | All permissions (superuser) |
When creating roles, permissions are validated against this pattern:
/^[a-zA-Z0-9_*-]+:[a-zA-Z0-9_*-]+$/
Examples of valid permission strings:
users:readbilling:managereports:exportposts:**:read