Authorization

The yorauth.roles and yorauth.permissions namespaces provide a full RBAC (role-based access control) interface. Roles are collections of permissions. Permissions follow a resource:action format (e.g., posts:create, users:delete).

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

All authorization methods require a valid JWT access token. See Authentication for how to obtain one.

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

typescript

const result = await yorauth.permissions.check({
  userId: 'user-uuid',
  permission: 'posts:create',
});

console.log(result.allowed);    // boolean
console.log(result.permission); // 'posts:create'
console.log(result.cached);     // boolean — was this served from cache

With ABAC context (Attribute-Based Access Control):

typescript

const result = await yorauth.permissions.check({
  userId: 'user-uuid',
  permission: 'documents:edit',
  resource: {
    type: 'document',
    id: 'doc-123',
    owner_id: 'user-uuid',
  },
  context: {
    department: 'engineering',
    time_of_day: 'business_hours',
  },
});

console.log(result.allowed);          // boolean
console.log(result.abac_evaluated);   // boolean
console.log(result.policies_checked); // number

Parameters:

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

Bulk Permission Check

Check multiple permissions in a single request. More efficient than multiple individual checks.

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

typescript

const { results } = await yorauth.permissions.checkBulk({
  userId: 'user-uuid',
  permissions: [
    'posts:create',
    'posts:read',
    'posts:delete',
    'users:manage',
  ],
});

// results is a map of permission -> { allowed: boolean }
console.log(results['posts:create'].allowed); // true
console.log(results['posts:delete'].allowed); // false

With ABAC context:

typescript

const { results } = await yorauth.permissions.checkBulk({
  userId: 'user-uuid',
  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`	`string[]`	Yes	Array of permissions (max 50)
`resource`	`object`	No	Resource attributes for ABAC policy evaluation
`context`	`object`	No	Request context attributes for ABAC policy evaluation

List Permissions

Retrieve all permissions defined for the application.

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

typescript

const { data } = await yorauth.permissions.list({
  page: 1,
  perPage: 25,
  search: 'posts',  // optional — filter by name
});

console.log(data.data);         // Permission[]
console.log(data.total);        // total count
console.log(data.current_page); // current page

Create a Permission

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

typescript

const { data } = await yorauth.permissions.create({
  name: 'posts:publish',
  resource: 'posts',
  action: 'publish',
  description: 'Allows publishing posts to the public feed',
});

console.log(data.id);   // uuid
console.log(data.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}

typescript

const { data } = await yorauth.permissions.get('permission-uuid');

console.log(data.id);
console.log(data.name);
console.log(data.description);

Update a Permission

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

typescript

const { data } = await yorauth.permissions.update('permission-uuid', {
  description: 'Updated description',
});

Delete a Permission

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

typescript

await yorauth.permissions.delete('permission-uuid');

Roles

Roles group one or more permissions and can be assigned to users.

List Roles

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

typescript

const { data } = await yorauth.roles.list({
  search: 'admin',            // optional
  includePermissions: true,   // optional — embed permissions in each role
  perPage: 15,
  page: 1,
});

data.data.forEach(role => {
  console.log(role.id);
  console.log(role.name);
  console.log(role.display_name);
  console.log(role.permissions_count);
});

Create a Role

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

typescript

const { data } = await yorauth.roles.create({
  name: 'editor',
  displayName: 'Editor',
  description: 'Can create and edit content',
  permissions: [
    'permission-uuid-1',
    'permission-uuid-2',
  ],
});

console.log(data.id);
console.log(data.name); // 'editor'

Parameters:

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

Get a Role

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

typescript

const { data } = await yorauth.roles.get('role-uuid');

console.log(data.id);
console.log(data.name);
console.log(data.permissions); // Permission[]
console.log(data.users_count);

Update a Role

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

typescript

const { data } = await yorauth.roles.update('role-uuid', {
  displayName: 'Senior Editor',
  description: 'Can create, edit, and publish content',
  permissions: [
    'permission-uuid-1',
    'permission-uuid-2',
    'permission-uuid-3', // newly added
  ],
});

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}

typescript

await yorauth.roles.delete('role-uuid');
// Throws 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

typescript

const { data } = await yorauth.roles.listForUser('user-uuid');

data.forEach(role => {
  console.log(role.id);
  console.log(role.name);
  console.log(role.scope);      // null or scope string
  console.log(role.expires_at); // null or ISO 8601 date
});

Assign a Role to a User

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

typescript

const { data } = await yorauth.roles.assign('user-uuid', {
  roleId: 'role-uuid',
  scope: 'team:engineering',  // optional — scope the assignment
  expiresAt: '2027-01-01T00:00:00Z', // optional — auto-expire the assignment
});

Parameters:

Parameter	Type	Required	Description
`roleId`	`string`	Yes	UUID of the role to assign
`scope`	`string`	No	Optional scope string (e.g., a team or resource identifier)
`expiresAt`	`string`	No	ISO 8601 datetime — the assignment expires automatically

Remove a Role from a User

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

typescript

await yorauth.roles.remove('user-uuid', 'role-uuid');

// Scoped removal:
await yorauth.roles.remove('user-uuid', 'role-uuid', {
  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

typescript

const { data } = await yorauth.permissions.getForUser('user-uuid');

console.log(data.permissions); // string[] — e.g. ['posts:create', 'posts:read']
console.log(data.roles);       // role names contributing to these permissions

Usage Patterns

Guard a UI Route

typescript

import { yorauth } from '@/lib/yorauth';

async function canAccessAdminPanel(userId: string): Promise<boolean> {
  const { allowed } = await yorauth.permissions.check({
    userId,
    permission: 'admin:access',
  });
  return allowed;
}

To minimize per-request checks in your frontend, load computed permissions once after login:

typescript

const session = await yorauth.auth.login({ email, password });
const userId = session.data.user.id;

const { data } = await yorauth.permissions.getForUser(userId);
// Cache locally for the session duration
const userPermissions = new Set(data.permissions);

// Later, check without an API call:
if (userPermissions.has('posts:create')) {
  // show create button
}