---
title: "List roles and their permissions"
url: https://docs.corefinity.com/api/reference/organisation/list-team-roles
type: endpoint
last_updated: 2026-11-13
feature: team
related:
  - https://docs.corefinity.com/guides/organisation/people/users-and-invitations.md
  - https://docs.corefinity.com/mcp/tools/corestack_team_roles_list.md
---
# List roles and their permissions

Answers your company's custom roles and the standard roles for your kind of company, by name, each with the
permissions it gives and whether you may give it to somebody.

```http
GET /api/team/roles
```

- Scope: `read`
- Rate limit: 60 a minute
- Try it in the console: on

## Request

### curl

```bash
curl https://manage.corefinity.com/api/team/roles \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json"
```

### PHP

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->get('https://manage.corefinity.com/api/team/roles');

$data = $response->json();
```

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/team/roles', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
  },
});

// An answer with no body (204) has nothing to parse.
const text = await res.text();
const data = text && JSON.parse(text);
```

### Python

```python
import os
import requests

res = requests.get(
    "https://manage.corefinity.com/api/team/roles",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
)

data = res.json() if res.content else None
```

## Responses

### 200 The roles.

```json
{
  "data": {
    "roles": [
      {
        "assignable": true,
        "custom": false,
        "id": 3012,
        "name": "Member (Full Access)",
        "permissions": [
          "viewWebsites",
          "viewDeployments",
          "viewTickets",
          "createTickets"
        ],
        "slug": "client-member-full"
      },
      {
        "assignable": true,
        "custom": true,
        "id": 3107,
        "name": "Release managers",
        "permissions": [
          "viewUsers"
        ],
        "slug": "release-managers-0b9c7a52-3f7e-4c1d-9a55-2f6f1f0e8d11"
      }
    ]
  }
}
```

### 401 No token, or a token that is not valid.

```json
{
  "message": "Unauthenticated."
}
```

### 403 The token lacks the scope this endpoint needs. `scope` names it.

```json
{
  "code": "scope_required",
  "message": "This access token does not have the destructive scope this needs. Use a token with the destructive scope.",
  "reason": "scope_required",
  "scope": "destructive"
}
```

### 429 Too many requests (`rate_limited`). Wait for the number of seconds in `Retry-After`, which `retry_after_seconds` repeats.

```json
{
  "code": "rate_limited",
  "message": "Too many requests. Try again in 60 seconds.",
  "reason": "rate_limited",
  "retry_after_seconds": 60
}
```

## If it is refused

| Status | Reason | What to do |
|---|---|---|
| 401 |  | Send a valid token as `Authorization: Bearer <token>`. |
| 403 | `scope_required` | Use a token with the scope named in `scope`. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |

## The same task elsewhere

- Guide: [Users and invitations](https://docs.corefinity.com/guides/organisation/people/users-and-invitations.md)
- MCP tool: [`corestack_team_roles_list`](https://docs.corefinity.com/mcp/tools/corestack_team_roles_list.md)
