> ## 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 in Arize.

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

Create and manage custom roles with fine-grained permissions for role-based access control in your Arize account.

## Key Capabilities

* List all roles (predefined and custom) in your account
* Retrieve a specific role by ID
* Create custom roles with specific permissions
* Update a custom role's name, description, or permissions
* Delete custom roles

## List Roles

List all roles available in your account. Optionally filter to predefined or custom roles only.

```python theme={null}
# List all roles
resp = client.roles.list()

for role in resp.roles:
    print(role.id, role.name, role.is_predefined)

# List only predefined (system) roles
resp = client.roles.list(is_predefined=True)

# List only custom roles
resp = client.roles.list(is_predefined=False)
```

For details on pagination, field introspection, and data conversion (to dict/JSON/DataFrame), see [Response Objects](/api-clients/python/version-8/overview#response-objects).

## Create a Role

Create a new custom role. Role names must be unique within the account. At least one permission must be provided. Predefined (system-managed) roles cannot be created through this endpoint.

```python theme={null}
from arize.roles.types import Permission

role = client.roles.create(
    name="AI Engineer",
    permissions=[
        Permission.PROJECT_READ,
        Permission.DATASET_READ,
        Permission.DATASET_CREATE,
    ],
    description="Can read projects and read/create datasets.",  # optional
)

print(role.id, role.name)
```

## Get a Role

Retrieve a specific role by its ID.

```python theme={null}
role = client.roles.get(role="your-role-name-or-id")

print(role.id, role.name)
print(role.permissions)
print(role.is_predefined)
```

## Update a Role

Update an existing custom role. At least one of `name`, `description`, or `permissions` must be provided. When `permissions` is provided, the existing permissions are fully replaced with the new set. Predefined roles cannot be updated.

```python theme={null}
role = client.roles.update(
    role="your-role-name-or-id",
    name="Updated Role Name",           # optional
    description="Updated description",  # optional
    permissions=[                        # optional — fully replaces existing permissions
        Permission.PROJECT_READ,
        Permission.DATASET_READ,
    ],
)

print(role.id, role.name)
```

## Delete a Role

Delete a custom role by ID. Predefined (system-managed) roles cannot be deleted.

```python theme={null}
client.roles.delete(role="your-role-name-or-id")
```