> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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. |