---
title: "Create a new role."
method: POST
path: "/api/v2/roles"
tags: ["Roles"]
---

# Create a new role.

`POST /api/v2/roles`

## Request

- Base URL: `https://console.jumpcloud.com`
- URL: `https://console.jumpcloud.com/api/v2/roles`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api/docs/api/v2/roles/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new role with the specified permissions.

## Request body

- RoleCreate
  - `name` string, required: Name of the role
  - `scopes` string[], required: List of permission scopes to assign to this role
  - `providerId` string: ID of the provider to associate with this role
  - `organizationIds` string[]: List of organization IDs to associate with this role
  - `description` string: Description of the role and its purpose

## Response `201`

Role created successfully.

- Role
  - `id` string: ID of the role
  - `name` string, required: Name of the role
  - `scopes` string[], required: List of permission scopes associated with this role.
  - `providerId` string: ID of the provider associated with this role.
  - `organizationIds` string[]: List of organization IDs this role is associated with.
  - `description` string: Description of the role and its purpose
  - `createdBy` string: ID of the user who created this role
  - `lastUpdatedBy` string: ID of the user who last updated this role
  - `isCustom` boolean: Indicates if this is a custom role (true) or a system role (false)
  - `ownerType` 'provider': Owner of the custom role. Set to `provider` for provider-owned (MSP) custom roles; omitted for organization-owned roles.

## Other responses

- `400`: Bad Request
- `401`: Unauthenticated
- `403`: Unauthorized
- `404`: Not Found
- `409`: Conflict
- `500`: Internal Server Error
- `default`: Unexpected error

---

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