---
title: "Update a role."
method: PUT
path: "/api/v2/roles/{role_id}"
tags: ["Roles"]
---

# Update a role.

`PUT /api/v2/roles/{role_id}`

## Request

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

Updates an existing role with the specified ID.

## Headers

- `x-org-id` string
- `x-provider-id` string

## Request body

- RoleUpdate
  - `name` string: Updated name of the role
  - `scopes` string[]: Updated list of permission scopes for 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
  - `organizations` object: Organization distribution delta for provider-owned custom roles.
    - `add` string[]
    - `remove` string[]

## Response `200`

Successfully retrieved the role.

- 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)