> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles

> Create and manage custom RBAC roles and their permissions using the Arize TypeScript SDK.

<Note>
  The `roles` functions are currently in **BETA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

## List Roles

```typescript theme={null}
import { listRoles } from "@arizeai/ax-client";

// List all roles (predefined and custom)
const { data: roles, pagination } = await listRoles();

// List only predefined (system) roles
const { data: predefined } = await listRoles({ isPredefined: true });

// List only custom roles
const { data: custom } = await listRoles({ isPredefined: false });
```

## Create a Role

Custom roles must have a unique name within the account and at least one permission. Predefined (system-managed) roles cannot be created through this endpoint.

```typescript theme={null}
import { createRole } from "@arizeai/ax-client";

const role = await createRole({
  name: "AI Engineer",
  permissions: ["PROJECT_READ", "DATASET_READ", "DATASET_CREATE"],
  description: "Can read projects and read/create datasets.",
});
console.log(role.id);
```

## Get a Role

```typescript theme={null}
import { getRole } from "@arizeai/ax-client";

const role = await getRole({ roleId: "your_role_id" });
console.log(role.name, role.permissions);
```

## Update a Role

At least one of `name`, `description`, or `permissions` must be provided. When `permissions` is provided, it fully replaces the existing permission set. Predefined roles cannot be updated.

```typescript theme={null}
import { updateRole } from "@arizeai/ax-client";

const updated = await updateRole({
  roleId: "your_role_id",
  permissions: ["PROJECT_READ", "DATASET_READ"],
});
```

## Delete a Role

Predefined (system-managed) roles cannot be deleted.

```typescript theme={null}
import { deleteRole } from "@arizeai/ax-client";

await deleteRole({ roleId: "your_role_id" });
```

## Role Fields

| Field          | Type                  | Description                                       |
| -------------- | --------------------- | ------------------------------------------------- |
| `id`           | `string`              | The role ID.                                      |
| `name`         | `string`              | The role name.                                    |
| `description`  | `string \| undefined` | Optional description.                             |
| `permissions`  | `Permission[]`        | List of permissions granted by this role.         |
| `isPredefined` | `boolean`             | Whether this is a system-managed predefined role. |
| `createdAt`    | `Date`                | When the role was created.                        |
| `updatedAt`    | `Date`                | When the role was last updated.                   |