---
title: "Replace a role set"
method: POST
path: "/role_sets/{role_set_key_or_id}/replace"
tags: ["Role Sets"]
---

# Replace a role set

`POST /role_sets/{role_set_key_or_id}/replace`

Replaces a role set with another role set. This is functionally equivalent to deleting
the role set but allows for atomic replacement with migration support.
Organizations using this role set will be migrated to the destination role set.

## Path parameters

- `role_set_key_or_id` string, required

## Request body

- object
  - `dest_role_set_key` string, required — The key of the destination role set
  - `reassignment_mappings` ReassignmentMappings — Mappings from source role keys to destination role keys for role reassignment

## Response `200`

Deleted Object

- DeletedObject
  - `object` string, required
  - `id` string
  - `slug` string
  - `deleted` boolean, required
  - `external_id` string

## Other responses

- `400` — Request was not successful
- `401` — Authentication invalid
- `403` — Authorization invalid
- `404` — Resource not found
- `422` — Invalid request parameters

---

[API](https://skmtc.dev/clerk/apis/clerk-backend-api.md) · [All operations](https://skmtc.dev/clerk/apis/clerk-backend-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/clerk/clerk-backend-api/revisions/75df3a43fcb2/schema)