---
title: "Replace a tenant role"
method: PUT
path: "/v1/Roles/definitions/{id}"
tags: ["Roles"]
---

# Replace a tenant role

`PUT /v1/Roles/definitions/{id}`

## Request

- Base URL: `https://api.invendor.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.invendor.com/v1/Roles/definitions/{id}`
- Auth: OAuth 2
  - Authorization code: `https://identity.scanbro.com/connect/authorize`
  - Token URL: `https://identity.scanbro.com/connect/token` scopes: `io.common`
- TypeScript: <https://skmtc.dev/invendor/apis/io-commonapi/docs/v1/Roles/definitions/:id/put.ts> (a function with typed inputs; its response is checked against the schema)

Only a user of the tenant primary account may edit roles (403 otherwise).
Predefined roles are read-only, and a role ranked above the caller can not be edited. The same
rank limit as creation applies. Portal
access follows the change within seconds; API calls follow when the holders' tokens refresh.

## Path parameters

- `id` string, required

## Query parameters

- `Account` unknown

## Request body

- RoleDefinitionRequest
  - `name` string, nullable
  - `description` string, nullable
  - `rank` integer
  - `permissions` string[], nullable

## Response `200`

Success

- RoleDefinitionResponse
  - `id` string, nullable
  - `name` string, nullable
  - `description` string, nullable
  - `rank` integer
  - `isSystem` boolean
  - `permissions` string[], nullable
  - `holderCount` integer
  - `canEdit` boolean
  - `canDelete` boolean
  - `canAssign` boolean

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict

## Changes

- **2026-10-12** `1239b9eaa9bb`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/invendor/apis/io-commonapi/changes/v1/Roles/definitions/:id/put.md)

---

[API](https://skmtc.dev/invendor/apis/io-commonapi.md) - [All operations](https://skmtc.dev/invendor/apis/io-commonapi/llms.txt) - [OpenAPI document](https://skmtc.dev/invendor/apis/io-commonapi/revisions/6a4a4fd7114d?raw)