---
title: "List the user roles"
description: "Start here to inspect permissions."
canonical: "https://grid82.com/docs/builder-api/roles/list"
updated: "2026-11-13"
---

# List the user roles

`GET https://studio.grid82.app/v1/apps/{appId}/roles`

Start here to inspect permissions.

List every app role, its member count, and one sentence per table describing what each role may see and do. All app permissions are decided by roles; rules never cross between roles. Add one with `roles.create`; check one with `rules.simulate`, without adding anyone.

Requires the `schema:read` scope. Operation `roles.list`. MCP tool `roles_list`. CLI: `grid82 roles list` (`npx grid82`).

## Path parameters

| Name    | Type   | Required | Description |
| ------- | ------ | -------- | ----------- |
| `appId` | string | yes      |             |

**Authorizations**

- `Authorization` (bearer, in header, required)

## Response

**200**: Success

- `data` (`object`, required)
- `data.roles` (`object[]`, required)
- `data.roles.id` (`string`, required)
- `data.roles.name` (`string`, required)
- `data.roles.description` (`string`, required)
- `data.roles.members` (`integer`, required)
- `data.roles.wholeDatabase` (`boolean`, required)
- `data.roles.tables` (`integer`, required)
- `data.roles.summary` (`string`, required)

```json
{
  "data": {
    "roles": [
      {
        "id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "members": 123,
        "wholeDatabase": true,
        "tables": 123,
        "summary": "<string>"
      }
    ]
  }
}
```

**4XX**: Refused

- `error` (`object`, required)
- `error.code` (`enum<string>`, required, one of: `not_found, forbidden, unauthenticated, validation_failed, conflict, rate_limited, payment_required, not_implemented, internal`)
- `error.message` (`string`, required)
- `error.details` (`Record<string, unknown>`)

```json
{
  "error": {
    "code": "not_found",
    "message": "<string>",
    "details": {}
  }
}
```

**Example request**

```bash
curl --request GET \
  --url 'https://studio.grid82.app/v1/apps/<appId>/roles' \
  --header 'Authorization: Bearer <token>'
```