Permission

A permission represents an individual access right that can be assigned to roles. Permissions define what actions users with a given role can perform within your application.

Permissions are defined at the environment level and can be assigned to both environment roles and organization roles. Each permission has a unique slug identifier that you use when assigning it to roles.

const permission = {
  object: 'permission',
  id: 'perm_01HXYZ123456789ABCDEFGHIJ',
  slug: 'documents:read',
  name: 'Read Documents',
  description: 'Allows reading documents',
  system: false,
  resourceTypeSlug: 'organization',
  createdAt: '2024-01-15T12:00:00.000Z',
  updatedAt: '2024-01-15T12:00:00.000Z',
};

Get a list of all permissions in your WorkOS environment.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const permissions = await workos.authorization.listPermissions();

Create a new permission in your WorkOS environment. The permission can then be assigned to environment roles and organization roles.

The slug must be unique within the environment and must be lowercase, containing only letters, numbers, hyphens, underscores, colons, periods, and asterisks.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const permission = await workos.authorization.createPermission({
  slug: 'documents:delete',
  name: 'Delete Documents',
  description: 'Allows deleting documents',
});

Retrieve a permission by its unique slug.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const permission = await workos.authorization.getPermission('documents:read');

Update an existing permission. Only the fields provided in the request body will be updated.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const permission = await workos.authorization.updatePermission(
  'documents:read',
  {
    name: 'View Documents',
    description: 'Allows viewing document contents',
  },
);

Delete an existing permission. System permissions cannot be deleted.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.authorization.deletePermission('documents:delete');