---
title: "Create a role in an organization"
method: POST
path: "/organizations/{id_organization}/roles"
tags: ["organization_roles"]
---

# Create a role in an organization

`POST /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`)

Creates a role with its permission list. The name must be unique within the organization (error `1205`) and every permission must be a valid organization permission (error `1201`).

Access: the caller needs either the client-level permission `client_organization_roles:create` or the organization-level permission `organization_roles:create`. 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

## Request body

- OrganizationsRolesOrganizationRoleInput: Name and permission list of an organization role. Both properties overwrite the stored value.
  - `name` string, required: Role name. Must be unique inside the organization.
  - `permissions` string[], required: Complete list of organization permissions granted by this role.

## Response `200`

Successful operation

- OrganizationsRolesOrganizationRoleOne
  - `rol` OrganizationsRolesOrganizationRole: An organization role as the API returns it. Note it exposes `total_users` and never the list of user identifiers.
    - `_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.

## 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 | | `1201` | Invalid organization permission detected | | `1205` | Role name already exists in this 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)