> ## 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

> List, get, create, update, and delete RBAC roles using the Arize Go SDK.

<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>

A role is a named set of permissions that can be bound to users on resources (see [Role Bindings](/api-clients/go/version-2/client-resources/role-bindings)). The `Get`, `Update`, and `Delete` methods accept either a role name or an ID — the SDK resolves names to IDs on your behalf. Predefined (system) roles cannot be updated or deleted. Reference permission identifiers through the `roles.Permissions` namespace (e.g. `roles.Permissions.ProjectRead`) rather than bare string literals.

## List Roles

`List` returns a paginated list of roles. Defaults to a page size of 50. `IsPredefined` is a tri-state pointer filter — `nil` returns both predefined and custom roles, a pointer to `true` returns only system-defined roles, and a pointer to `false` returns only custom roles.

**Signature:**

```go theme={null}
func (c *Client) List(ctx context.Context, req ListRequest) (*RoleList, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/roles"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    customOnly := false
    resp, err := client.Roles.List(context.Background(), roles.ListRequest{
        IsPredefined: &customOnly,
        Limit:        25,
    })
    if err != nil {
        var unauthorized *arize.UnauthorizedError
        if errors.As(err, &unauthorized) {
            log.Fatalf("unauthorized: %v", unauthorized)
        }
        log.Fatal(err)
    }

    for _, role := range resp.Roles {
        fmt.Printf("%s: %s\n", role.Id, role.Name)
    }
}
```

## Get a Role

`Get` returns a single role, resolving by name or ID.

**Signature:**

```go theme={null}
func (c *Client) Get(ctx context.Context, req GetRequest) (*Role, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/roles"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    role, err := client.Roles.Get(
        context.Background(),
        roles.GetRequest{Role: "your-role-name-or-id"},
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("role not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("role %s: %s\n", role.Id, role.Name)
}
```

## Create a Role

`Create` issues a `POST` to create a new role and returns the created role. At least one permission is required; reference them through the `roles.Permissions` namespace.

**Signature:**

```go theme={null}
func (c *Client) Create(
    ctx context.Context,
    req CreateRequest,
) (*Role, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/roles"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    role, err := client.Roles.Create(
        context.Background(),
        roles.CreateRequest{
            Name: "read-only-analyst",
            Permissions: []roles.Permission{
                roles.Permissions.ProjectRead,
            },
        },
    )
    if err != nil {
        var conflict *arize.ConflictError
        if errors.As(err, &conflict) {
            log.Fatalf("role already exists: %v", conflict)
        }
        log.Fatal(err)
    }

    fmt.Printf("created role %s\n", role.Id)
}
```

## Update a Role

`Update` patches an existing role, resolving the target by name or ID, and returns the updated role. `Name`, `Description`, and `Permissions` are pointers — `nil` preserves the existing value. When `Permissions` is non-nil it replaces the existing permission set and must contain at least one permission (the server rejects empty arrays).

**Signature:**

```go theme={null}
func (c *Client) Update(
    ctx context.Context,
    req UpdateRequest,
) (*Role, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/roles"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    newPermissions := []roles.Permission{
        roles.Permissions.ProjectRead,
        roles.Permissions.ProjectUpdate,
    }
    role, err := client.Roles.Update(
        context.Background(),
        roles.UpdateRequest{
            Role:        "your-role-name-or-id",
            Permissions: &newPermissions,
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("role not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("updated role %s\n", role.Id)
}
```

## Delete a Role

`Delete` removes a role, resolving by name or ID. Predefined (system) roles cannot be deleted. It returns only an error.

**Signature:**

```go theme={null}
func (c *Client) Delete(ctx context.Context, req DeleteRequest) error
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/roles"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    err = client.Roles.Delete(
        context.Background(),
        roles.DeleteRequest{Role: "your-role-name-or-id"},
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Printf("no role to remove: %v", notFound)
            return
        }
        log.Fatal(err)
    }
}
```