# Roles

## Role Model

### Fields

- **`object`** `"role"`

- **`id`** `string`

- **`name`** `string`

- **`team_id`** `string`

- **`scopes`** [`Scopes`](/api/roles#scopes)

   The permissions the role grants: each resource mapped to its allowed actions (`read`, `write`,
   `delete`).

### Referenced Types

#### Scopes

`Record<string, ("read" | "write" | "delete")[]>`

Scope names mapped to their permitted actions. Allowed scope keys: `"users"`, `"roles"`, `"keys"`, `"records"`, `"projects"`, `"metrics"`, `"views"`, `"billing"`, `"pages"`, `"monitors"`, `"alerts"`, `"chats"`, `"secrets"`, `"servers"`, `"ingest_keys"`, `"sources"`, `"domains"`, `"facets"`, `"drains"`, `"pulls"`, `"checks"`, `"logs"`. Allowed action values: `"read"`, `"write"`, `"delete"`.

#### Scope

`"users" | "roles" | "keys" | "records" | "projects" | "metrics" | "views" | "billing" | "pages" | "monitors" | "alerts" | "chats" | "secrets" | "servers" | "ingest_keys" | "sources" | "domains" | "facets" | "drains" | "pulls" | "checks" | "logs"`

#### ScopeValue

`"read" | "write" | "delete"`

## List Roles

### Endpoint

Retrieve a list of roles for the current team.

```http
GET /v1/roles
```

**Scope:** `roles:read`

### Query Parameters

- **`order_by`** `string`
  Field used to order the roles. Optional. Defaults to `"name"`. Allowed values: `"name"`.

- **`limit`** `number`
  Optional. Defaults to `25`. Minimum: `1`. Maximum: `200`.

- **`after`** `string`
  Cursor from `pagination.next_cursor` of a previous response. Returns the resources after that page. Optional.

- **`before`** `string`
  Cursor from `pagination.prev_cursor` of a previous response. Returns the resources before that page. Optional.

- **`sort`** `string`
  Optional. Defaults to `"asc"`. Allowed values: `"asc"`, `"desc"`.

### Response

```ts
{
  message: string;
  data: Role[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}
```

### Comments

- `after` and `before` are mutually exclusive.

## Retrieve Role

### Endpoint

Retrieve a single role.

```http
GET /v1/roles/:role_id
```

**Scope:** `roles:read`

### Path Parameters

- **`role_id`** `string` -- **Required**
  Unique identifier of the role.

### Response

Role retrieved

```ts
{
  message: string;
  data: Role;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}
```

## Create Role

### Endpoint

Create a new role for the current team.

```http
POST /v1/roles
```

**Scope:** `roles:write`

### Request Body

- **`id`** `string`
  Custom identifier for the role. One is generated when omitted. Optional.

- **`name`** `string` -- **Required**
  Display name for the role. Minimum length: `2`. Maximum length: `60`.

- **`scopes`** [`Scopes`](/api/roles#scopes)
  Scope names mapped to their permitted actions. Optional. Allowed scope keys: `"users"`, `"roles"`, `"keys"`, `"records"`, `"projects"`, `"metrics"`, `"views"`, `"billing"`, `"pages"`, `"monitors"`, `"alerts"`, `"chats"`, `"secrets"`, `"servers"`, `"ingest_keys"`, `"sources"`, `"domains"`, `"facets"`, `"drains"`, `"pulls"`, `"checks"`, `"logs"`. Allowed action values: `"read"`, `"write"`, `"delete"`.

### Response

```ts
{
  message: string;
  data: Role;
  status: 201;
  error: null;
  pagination: null;
  endpoint: string;
}
```

### Comments

- `id` cannot be `role_owner`, which is reserved.
- Omit `id` and one is generated for you.
- You can assign only scopes that your own authorization has.
- The built-in `role_owner` role cannot be created, updated, or deleted.
- Human roles must include `projects:read`.

## Update Role

### Endpoint

Update an existing role.

```http
POST /v1/roles/:role_id
```

**Scope:** `roles:write`

### Path Parameters

- **`role_id`** `string` -- **Required**
  Unique identifier of the role.

### Request Body

- **`name`** `string`
  Display name for the role. Optional. Minimum length: `2`. Maximum length: `60`.

- **`scopes`** [`Scopes`](/api/roles#scopes)
  Scope names mapped to their permitted actions. Optional. Allowed scope keys: `"users"`, `"roles"`, `"keys"`, `"records"`, `"projects"`, `"metrics"`, `"views"`, `"billing"`, `"pages"`, `"monitors"`, `"alerts"`, `"chats"`, `"secrets"`, `"servers"`, `"ingest_keys"`, `"sources"`, `"domains"`, `"facets"`, `"drains"`, `"pulls"`, `"checks"`, `"logs"`. Allowed action values: `"read"`, `"write"`, `"delete"`.

### Response

Your role has been updated.

```ts
{
  message: string;
  data: Role;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}
```

### Comments

- A role's `id` cannot be changed. Every user assignment points at it, so a rename would orphan them.
- You can assign only scopes that your own authorization has.
- The built-in `role_owner` role cannot be created, updated, or deleted.
- Human roles must include `projects:read`.

## Delete Role

### Endpoint

Delete a role from the current team.

```http
DELETE /v1/roles/:role_id
```

**Scope:** `roles:delete`

### Path Parameters

- **`role_id`** `string` -- **Required**
  Unique identifier of the role.

### Response

```ts
{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}
```

### Comments

- Roles with assigned users cannot be deleted. Reassign those users before deleting the role.
- The built-in `role_owner` role cannot be created, updated, or deleted.