<!-- llms.txt: https://workos.com/llms.txt -->

# Roles and permissions

Define the roles available to an organization, the permissions attached to them, and the permissions a given member effectively holds.

## Assign a permission to a role

Grant a permission to a role belonging to the organization the token was issued for.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation AssignPermissionToRole($input: AssignPermissionToRoleInput!) {
  assignPermissionToRole(input: $input) {
    createdAt
    description
    id
    isDefault
    name
    slug
    updatedAt
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "assignPermissionToRole": {
      "createdAt": "2024-01-01T00:00:00.000Z",
      "description": "description_example",
      "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "isDefault": true,
      "name": "name_example",
      "slug": "slug_example",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

:::

## Create a role

Create a role for the organization the token was issued for.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation CreateRole($input: CreateRoleInput!) {
  createRole(input: $input) {
    createdAt
    description
    id
    isDefault
    name
    slug
    updatedAt
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "createRole": {
      "createdAt": "2024-01-01T00:00:00.000Z",
      "description": "description_example",
      "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "isDefault": true,
      "name": "name_example",
      "slug": "slug_example",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

:::

## Delete a role

Delete a role belonging to the organization the token was issued for.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation DeleteRole($input: DeleteRoleInput!) {
  deleteRole(input: $input) {
    id
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "deleteRole": {
      "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY"
    }
  }
}
```

:::

## List effective permissions

The permissions a user effectively has in the organization the token was issued for, including permissions inherited through the user's roles. Callers may read their own effective permissions; reading another member's requires the elevated user:read grant.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query EffectivePermissions($userId: ID!) {
  effectivePermissions(userId: $userId) {
    createdAt
    description
    id
    name
    slug
    system
    updatedAt
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "effectivePermissions": [
      {
        "createdAt": "2024-01-01T00:00:00.000Z",
        "description": "description_example",
        "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
        "name": "name_example",
        "slug": "slug_example",
        "system": true,
        "updatedAt": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}
```

:::

## List permissions

List the permissions defined in the environment the token was issued for.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query Permissions($after: String, $before: String, $limit: Int, $order: PaginationOrder, $search: String) {
  permissions(after: $after, before: $before, limit: $limit, order: $order, search: $search) {
    data {
      createdAt
      description
      id
      name
      slug
      system
      updatedAt
    }
    listMetadata {
      after
      before
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "permissions": {
      "data": [
        {
          "createdAt": "2024-01-01T00:00:00.000Z",
          "description": "description_example",
          "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
          "name": "name_example",
          "slug": "slug_example",
          "system": true,
          "updatedAt": "2024-01-01T00:00:00.000Z"
        }
      ],
      "listMetadata": {
        "after": "after_example",
        "before": "before_example"
      }
    }
  }
}
```

:::

## Get a role

Fetch a single role available to the organization the token was issued for.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query Role($id: ID!) {
  role(id: $id) {
    createdAt
    description
    id
    isDefault
    name
    slug
    updatedAt
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "role": {
      "createdAt": "2024-01-01T00:00:00.000Z",
      "description": "description_example",
      "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "isDefault": true,
      "name": "name_example",
      "slug": "slug_example",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

:::

## List roles

List roles available to the organization the token was issued for, with role assignment configuration.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query Roles {
  roles {
    multipleRolesEnabled
    roles {
      createdAt
      description
      id
      isDefault
      name
      slug
      updatedAt
    }
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "roles": {
      "multipleRolesEnabled": true,
      "roles": [
        {
          "createdAt": "2024-01-01T00:00:00.000Z",
          "description": "description_example",
          "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
          "isDefault": true,
          "name": "name_example",
          "slug": "slug_example",
          "updatedAt": "2024-01-01T00:00:00.000Z"
        }
      ]
    }
  }
}
```

:::

## Update a role

Update a role belonging to the organization the token was issued for.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation UpdateRole($input: UpdateRoleInput!) {
  updateRole(input: $input) {
    createdAt
    description
    id
    isDefault
    name
    slug
    updatedAt
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "updateRole": {
      "createdAt": "2024-01-01T00:00:00.000Z",
      "description": "description_example",
      "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "isDefault": true,
      "name": "name_example",
      "slug": "slug_example",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

:::

### Mutation assignPermissionToRole

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `permissionSlug` | String! | Yes | The slug of the permission to assign. |
| `roleId` | ID! | Yes | The ID of the role to assign the permission to. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | DateTime! |  |
| `description` | String |  |
| `id` | ID! |  |
| `isDefault` | Boolean! | Whether this is the default role assigned to new members. |
| `name` | String! |  |
| `slug` | String! |  |
| `updatedAt` | DateTime! |  |

### Mutation createRole

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | String | No | Optional human-readable description of the role. |
| `name` | String! | Yes | Human-readable name for the role. |
| `permissions` | [String!] | No | Slugs of the permissions granted to the role. |
| `slug` | String | No | Unique slug identifying the role. Generated from the name when omitted. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | DateTime! |  |
| `description` | String |  |
| `id` | ID! |  |
| `isDefault` | Boolean! | Whether this is the default role assigned to new members. |
| `name` | String! |  |
| `slug` | String! |  |
| `updatedAt` | DateTime! |  |

### Mutation deleteRole

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | ID! | Yes | The ID of the role to delete. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `id` | ID! | The ID of the deleted role. |

### Query effectivePermissions

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | ID! | Yes |  |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | DateTime! |  |
| `description` | String |  |
| `id` | ID! |  |
| `name` | String! |  |
| `slug` | String! |  |
| `system` | Boolean! | Whether this is a WorkOS-managed system permission that cannot be modified. |
| `updatedAt` | DateTime! |  |

### Query permissions

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `after` | String | No |  |
| `before` | String | No |  |
| `limit` | Int | No |  |
| `order` | PaginationOrder | No | Enum represents the pagination order. |
| `search` | String | No | Filter permissions by slug. Matches any permission whose slug contains the value, case-insensitively. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `data` | [Permission!]! | A permission that can be granted to a role within the environment. |
| `listMetadata` | ListMetadata! |  |

### Query role

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | ID! | Yes |  |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | DateTime! |  |
| `description` | String |  |
| `id` | ID! |  |
| `isDefault` | Boolean! | Whether this is the default role assigned to new members. |
| `name` | String! |  |
| `slug` | String! |  |
| `updatedAt` | DateTime! |  |

### Query roles

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `multipleRolesEnabled` | Boolean! | Whether members can be assigned multiple roles simultaneously. |
| `roles` | [Role!]! | A role available within the organization. |

### Mutation updateRole

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | String | No | Human-readable description of the role. This is a full replace of the role, so an omitted or null description clears it — resupply the current value to preserve it. |
| `id` | ID! | Yes | The ID of the role to update. |
| `name` | String! | Yes | Human-readable name for the role. |
| `permissions` | [String!] | No | Slugs of the permissions granted to the role. Replaces the existing set when provided. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | DateTime! |  |
| `description` | String |  |
| `id` | ID! |  |
| `isDefault` | Boolean! | Whether this is the default role assigned to new members. |
| `name` | String! |  |
| `slug` | String! |  |
| `updatedAt` | DateTime! |  |