---
title: "Create a tenant role"
method: POST
path: "/v1/Roles/definitions"
tags: ["Roles"]
---

# Create a tenant role

`POST /v1/Roles/definitions`

## 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`
- 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/post.ts> (a function with typed inputs; its response is checked against the schema)

Only a user of the tenant primary account may create roles (403 otherwise).
The role may not be ranked above the caller (lower rank is more privileged). It may contain any
permission in the catalogue: holding Roles.Manage is enough, the caller need not hold them. The name must be unique in the tenant and may not be a predefined
role's name. To duplicate a role, read it and post its permissions under a new name.

## Query parameters

- `Account` unknown

## Request body

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

## Response `201`

Created

- 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
- `409`: Conflict

## Changes

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

[Operation history](https://skmtc.dev/invendor/apis/io-commonapi/changes/v1/Roles/definitions/post.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)