---
title: List
url: https://www.tines.com/docs/api/admin/roles/list/
updated: 2026-04-09T14:16:42+00:00
description: Retrieve a list of roles (both default and custom) from the Tines tenant.
---

*[tines.com](https://www.tines.com/llms.txt) › [Docs](https://www.tines.com/llms.txt) › [Tines API](https://www.tines.com/llms.txt) › [Admin](https://www.tines.com/llm/docs/api/admin.md) › [Roles](https://www.tines.com/llm/docs/api/admin/roles.md)*

# List

*[View on tines.com](https://www.tines.com/docs/api/admin/roles/list/)*

## Description

Retrieve a list of roles (both default and custom) from the Tines tenant.

## Request

HTTP Method: **GET**

| Query Parameter | Description                                                                                         |
| --------------- | --------------------------------------------------------------------------------------------------- |
| per_page        | **Optional** Set the number of results returned per page. Defaults to 20.                           |
| page            | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. |

```bash
curl -X GET \
  https://<tenant-domain>/api/v1/admin/roles \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'
```

## Response

A successful request will return a JSON Array of roles in the Tines tenant.

### Field description

| Parameter   | Description                                                                      |
| ----------- | -------------------------------------------------------------------------------- |
| id          | Role ID.                                                                         |
| name        | Role name.                                                                       |
| type        | Role type - custom or default.                                                   |
| description | Role description.                                                                |
| permissions | Array of applied permissions.                                                    |
| created_at  | Timestamp describing when the role was created.                                  |
| updated_at  | Timestamp describing when the role was last updated.                             |
| builder     | Boolean indicating whether this role grants builder / story editing permissions. |

### Sample response

<!-- cspell:disable -->

```json
{
  "admin/roles": [
    {
      "id": "TEAM_ADMIN",
      "name": "TEAM_ADMIN",
      "type": "default",
      "description": "Manage members, stories, credentials, resources and change control.",
      "permissions": ["ALLOW_ALL"],
      "created_at": null,
      "updated_at": null,
      "builder": true
    },
    {
      "id": "123",
      "name": "MY_ROLE",
      "type": "custom",
      "description": "My fantastic role",
      "permissions": ["STORY_CREATE"],
      "created_at": "2019-11-03T09:57:49.537Z",
      "updated_at": "2019-11-03T09:57:49.537Z",
      "builder": true
    }
  ],
  "meta": {
    "current_page": "https://<tenant-domain>/api/v1/admin/roles?page=1&per_page=20",
    "previous_page": null,
    "next_page": null,
    "next_page_number": null,
    "per_page": 20,
    "pages": 1,
    "count": 2
  }
}
```

<!-- cspell:enable -->