> ## Documentation Index
> Fetch the complete documentation index at: https://docs.member.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Read team roles

> Read and update role descriptions, assigned permission slugs and current member counts.

A role groups permission assignments for team members. Role resources include
`attributes.permissions`, the assigned permission slugs in alphabetical order.
A role with no assignments returns an empty array, `[]`.

Use a platform user access token. API keys cannot read or manage roles. A team
role is visible to its active team's members and owner, and to platform admins.
A caller outside that team receives `404`. Global roles are visible to every
signed-in platform user.

## Read a role

```bash theme={null}
curl 'https://api.member.dev/api/v1/roles/ROLE_ID' \
  -H "Authorization: Bearer $PLATFORM_ACCESS_TOKEN" \
  -H 'Accept: application/vnd.api+json'
```

The response includes:

```json theme={null}
{
  "data": {
    "type": "roles",
    "id": "ROLE_ID",
    "attributes": {
      "name": "Media editor",
      "slug": "media-editor",
      "team_id": "TEAM_ID",
      "is_system": false,
      "permissions": ["media.edit"],
      "description": "Manage the team's media library",
      "member_count": 3
    }
  }
}
```

`GET /api/v1/roles` returns the same field on every visible role. Role creation,
rename and permission-assignment responses also return the current assignments.
Removing an assignment returns `204`; retrieve the role again to read its updated
permissions.

Use these stored assignments to display or edit a role. Effective access also
depends on ownership, permission bundles, active team membership, the requested
resource and other access checks. Reading this array does not change who can
manage the role or assign permissions. Team roles apply across the team.

## Describe a role

`description` is nullable text up to 200 characters. You can supply it when
creating a role or update it as the team's owner or a platform admin. Global
roles are managed by platform admins. System roles and the built-in Admin role
remain locked.

```bash theme={null}
curl -X PATCH 'https://api.member.dev/api/v1/roles/ROLE_ID' \
  -H "Authorization: Bearer $PLATFORM_ACCESS_TOKEN" \
  -H 'Content-Type: application/vnd.api+json' \
  --data '{"description":"Manage the team media library"}'
```

Omitting `description` from a PATCH preserves it. Send `null` to clear it or an
empty string to store an empty description. Text over 200 characters returns
`422`. An ordinary team member can read a visible role's description but cannot
change it.

## Read the member count

`member_count` is the number of current active team members assigned to that
role. It excludes pending invitations, removed memberships, deleted or inactive
users, deleted teams and assignments belonging to a different team. A team role
with no matching assignments returns `0`.

Global roles return `null` for this field; their cross-team totals are not
published. Counts are computed for each response and are available wherever the
role itself is visible, including the list response.
`member_count` is read-only: supplying it in a create or update request returns
`422`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.