Authorization

The $yorauth->roles() and $yorauth->permissions() resources provide a full RBAC interface. Roles group permissions. Permissions follow a resource:action format (e.g., posts:create, users:delete).

The PHP SDK is currently in development. This documentation describes the intended API. The package is not yet published to Packagist.

Permissions

Permissions in YorAuth use the format resource:action. Examples: posts:create, posts:read, users:delete, billing:manage.

Check a Single Permission

Check whether a user has a specific permission. Results are cached server-side (Redis, 1-hour TTL).

API endpoint: GET /api/v1/applications/{applicationId}/authz/check

php

$result = $yorauth->permissions()->check($userId, 'posts:create');

var_dump($result['allowed']);    // bool(true)
echo $result['permission'];      // 'posts:create'
var_dump($result['cached']);     // bool(true) — served from cache

With ABAC context (Attribute-Based Access Control):

php

$result = $yorauth->permissions()->check(
    userId: $userId,
    permission: 'documents:edit',
    resource: [
        'type'     => 'document',
        'id'       => 'doc-123',
        'owner_id' => $userId,
    ],
    context: [
        'department'  => 'engineering',
        'time_of_day' => 'business_hours',
    ],
);

var_dump($result['allowed']);          // bool
var_dump($result['abac_evaluated']);   // bool
echo $result['policies_checked'];      // int

Parameters:

Parameter	Type	Required	Description
`$userId`	`string`	Yes	The user ID to check permissions for
`$permission`	`string`	Yes	Permission in `resource:action` format
`$resource`	`array`	No	Resource attributes for ABAC policy evaluation
`$context`	`array`	No	Request context attributes for ABAC policy evaluation

Bulk Permission Check

Check multiple permissions in a single request.

API endpoint: POST /api/v1/applications/{applicationId}/authz/check-bulk

php

$response = $yorauth->permissions()->checkBulk(
    userId: $userId,
    permissions: [
        'posts:create',
        'posts:read',
        'posts:delete',
        'users:manage',
    ],
);

$results = $response['results'];

var_dump($results['posts:create']['allowed']); // bool(true)
var_dump($results['posts:delete']['allowed']); // bool(false)

With ABAC context:

php

$response = $yorauth->permissions()->checkBulk(
    userId: $userId,
    permissions: ['documents:read', 'documents:edit'],
    resource: ['type' => 'document', 'id' => 'doc-123'],
    context: ['environment' => 'production'],
);

The bulk check endpoint accepts up to 50 permissions per request.

Parameters:

Parameter	Type	Required	Description
`$userId`	`string`	Yes	The user ID to check permissions for
`$permissions`	`array`	Yes	Array of permission strings (max 50)
`$resource`	`array`	No	Resource attributes for ABAC policy evaluation
`$context`	`array`	No	Request context attributes for ABAC policy evaluation

List Permissions

API endpoint: GET /api/v1/applications/{applicationId}/permissions

php

$page = $yorauth->permissions()->list([
    'page'     => 1,
    'per_page' => 25,
    'search'   => 'posts', // optional
]);

foreach ($page['data'] as $permission) {
    echo $permission['id'];
    echo $permission['name'];
}
echo $page['total'];

Create a Permission

API endpoint: POST /api/v1/applications/{applicationId}/permissions

php

$permission = $yorauth->permissions()->create([
    'name'        => 'posts:publish',
    'resource'    => 'posts',
    'action'      => 'publish',
    'description' => 'Allows publishing posts to the public feed',
]);

echo $permission['id'];
echo $permission['name']; // 'posts:publish'

Parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes	Full permission name in `resource:action` format
`resource`	`string`	No	Resource portion (derived from `name` if omitted)
`action`	`string`	No	Action portion (derived from `name` if omitted)
`description`	`string`	No	Human-readable description

Get a Permission

API endpoint: GET /api/v1/applications/{applicationId}/permissions/{permissionId}

php

$permission = $yorauth->permissions()->get('permission-uuid');

Update a Permission

API endpoint: PUT /api/v1/applications/{applicationId}/permissions/{permissionId}

php

$permission = $yorauth->permissions()->update('permission-uuid', [
    'description' => 'Updated description',
]);

Delete a Permission

API endpoint: DELETE /api/v1/applications/{applicationId}/permissions/{permissionId}

php

$yorauth->permissions()->delete('permission-uuid');

Roles

List Roles

API endpoint: GET /api/v1/applications/{applicationId}/roles

php

$page = $yorauth->roles()->list([
    'search'              => 'admin',
    'include_permissions' => true,
    'per_page'            => 15,
    'page'                => 1,
]);

foreach ($page['data'] as $role) {
    echo $role['id'];
    echo $role['name'];
    echo $role['display_name'];
    echo $role['permissions_count'];
}

Create a Role

API endpoint: POST /api/v1/applications/{applicationId}/roles

php

$role = $yorauth->roles()->create([
    'name'         => 'editor',
    'display_name' => 'Editor',
    'description'  => 'Can create and edit content',
    'permissions'  => [
        'permission-uuid-1',
        'permission-uuid-2',
    ],
]);

echo $role['id'];
echo $role['name']; // 'editor'

Parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes	Machine-readable role name (slug format)
`display_name`	`string`	No	Human-readable name shown in the dashboard
`description`	`string`	No	Description of what this role grants
`permissions`	`array`	No	Array of permission UUIDs

Get a Role

API endpoint: GET /api/v1/applications/{applicationId}/roles/{roleId}

php

$role = $yorauth->roles()->get('role-uuid');

echo $role['id'];
echo $role['name'];
print_r($role['permissions']); // array of Permission
echo $role['users_count'];

Update a Role

API endpoint: PUT /api/v1/applications/{applicationId}/roles/{roleId}

php

$role = $yorauth->roles()->update('role-uuid', [
    'display_name' => 'Senior Editor',
    'description'  => 'Can create, edit, and publish content',
    'permissions'  => [
        'permission-uuid-1',
        'permission-uuid-2',
        'permission-uuid-3',
    ],
]);

The permissions array replaces the current permission set when provided. Omit it to leave permissions unchanged.

Delete a Role

API endpoint: DELETE /api/v1/applications/{applicationId}/roles/{roleId}

php

$yorauth->roles()->delete('role-uuid');
// Throws YorAuthException if the role is a system role or still assigned to users.

User Role Assignments

List a User's Roles

API endpoint: GET /api/v1/applications/{applicationId}/users/{userId}/roles

php

$result = $yorauth->roles()->listForUser($userId);

foreach ($result['data'] as $role) {
    echo $role['id'];
    echo $role['name'];
    echo $role['scope'];       // null or scope string
    echo $role['expires_at'];  // null or ISO 8601 datetime
}

Assign a Role to a User

API endpoint: POST /api/v1/applications/{applicationId}/users/{userId}/roles

php

$assignment = $yorauth->roles()->assign($userId, [
    'role_id'    => 'role-uuid',
    'scope'      => 'team:engineering', // optional
    'expires_at' => '2027-01-01T00:00:00Z', // optional
]);

Parameters:

Parameter	Type	Required	Description
`role_id`	`string`	Yes	UUID of the role to assign
`scope`	`string`	No	Optional scope string
`expires_at`	`string`	No	ISO 8601 datetime — the assignment auto-expires

Remove a Role from a User

API endpoint: DELETE /api/v1/applications/{applicationId}/users/{userId}/roles/{roleId}

php

$yorauth->roles()->remove($userId, $roleId);

// Scoped removal:
$yorauth->roles()->remove($userId, $roleId, scope: 'team:engineering');

Get a User's Computed Permissions

Returns all permissions the user holds across all assigned roles.

API endpoint: GET /api/v1/applications/{applicationId}/users/{userId}/permissions

php

$result = $yorauth->permissions()->getForUser($userId);

$result['permissions']; // ['posts:create', 'posts:read', ...]
$result['roles'];       // role names contributing to these permissions

Laravel Usage Examples

Policy Class

php

namespace App\Policies;

use App\Models\Post;
use App\Models\User;
use YorAuth\Laravel\Facades\YorAuth;

class PostPolicy
{
    public function create(User $user): bool
    {
        $result = YorAuth::permissions()->check(
            $user->yorauth_user_id,
            'posts:create',
        );

        return $result['allowed'];
    }

    public function update(User $user, Post $post): bool
    {
        $result = YorAuth::permissions()->check(
            userId: $user->yorauth_user_id,
            permission: 'posts:edit',
            resource: [
                'type'     => 'post',
                'id'       => $post->id,
                'owner_id' => $post->user_id,
            ],
        );

        return $result['allowed'];
    }
}

Bulk Check in a Controller

php

public function index(Request $request): JsonResponse
{
    $userId = $request->user()->id;

    $checks = YorAuth::permissions()->checkBulk(
        userId: $userId,
        permissions: ['posts:create', 'posts:delete', 'posts:publish'],
    );

    return response()->json([
        'posts'       => Post::all(),
        'permissions' => $checks['data']['results'],
    ]);
}