---
title: "List the roles of an organization"
method: GET
path: "/organizations/{id_organization}/roles"
tags: ["organization_roles"]
---

# List the roles of an organization

`GET /organizations/{id_organization}/roles`

## Request

- Base URL: `https://api.planvortex.com/v1.0.0`
- URL: `https://api.planvortex.com/v1.0.0/organizations/{id_organization}/roles`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (client credentials, token URL `https://api.planvortex.com/v1.0.0/oauth/token`)

Returns the roles defined in the organization, paginated.

Access: the caller needs either the client-level permission `client_organization_roles:read` or the organization-level permission `organization_roles:read`. Every endpoint under this organization also requires the client plan to allow at least 2 users (error `511` otherwise).

## Path parameters

- `id_organization` string, required

## Query parameters

- `offset` integer
- `limit` integer

## Response `200`

Successful operation

- OrganizationsRolesOrganizationRoleList
  - `roles` OrganizationsRolesOrganizationRole[]
    - `_id` string: Role identifier.
    - `id_organization` string: Organization the role belongs to.
    - `name` string: Role name.
    - `default` boolean: Whether this is a default role. Default roles cannot be updated or deleted, and their last user cannot be removed.
    - `permissions` string[]: Organization permissions granted by this role.
    - `total_users` integer: Number of users in the role.
    - `creation_date` string, date-time: When the role was created.
  - `total` integer: Total number of roles in the organization, ignoring pagination.

## Other responses

- `400`: The request failed. The body carries the PlanVortex error code in `code`: | Code | Meaning | | --- | --- | | `501` | Invalid authorization token | | `511` | This functionality requires a plan with at least 2 users | | `518` | User or application deleted | | `522` | Invalid token: expired | | `1101` | Invalid organization |
- `401`: Insufficient permissions. The body carries error code `520` with the permissions that were required.
- `500`: Unhandled error by the server (PlanVortex error code `500`).

---

[API](https://skmtc.dev/planvortex/apis/planvortex-api.md) · [All operations](https://skmtc.dev/planvortex/apis/planvortex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/planvortex/apis/planvortex-api/revisions/abedbbc1cd52?raw)