Create role

post

https://api.doit.com/iam/v1/roles

Creates a custom role in the authenticated customer with the given permission IDs. Permission IDs are the permissions values returned by GET /iam/v1/roles. A service account of a parent tenant can create the role in a descendant tenant by setting X-Tenant-Id to that tenant's customer ID. Requires the Idempotency-Key header so a retried request does not create a second role.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Request body to create a custom role.

name

string

required

length ≥ 1

The name of the role. Must be nonblank, contain no leading or trailing whitespace, and be unique among the customer's roles, including preset roles.

description

string

The description of the role.

permissions

array of strings, unique

Permission IDs to assign to the role, as returned in permissions by GET /iam/v1/roles. Duplicate IDs are rejected. Input order is preserved. Omission or an empty array creates a role without permissions.

permissions

Headers

Idempotency-Key

string

required

length between 1 and 255

Caller-chosen key (1-255 characters) that makes retries safe; the same key with the same body returns the original response.

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

201Created - Role created.

400Bad Request - Missing, blank or whitespace-padded name, duplicate permission IDs, or a permission ID that does not exist or is not available to the customer. A missing Idempotency-Key returns application/problem+json.

401Unauthorized - Invalid API key.

403Forbidden - The client is not authorized to perform the request.

409Conflict - A role with the same name already exists for the customer. The same Idempotency-Key still being processed by another request returns application/problem+json.

422Unprocessable Entity - The Idempotency-Key was already used with a different request body.

500Internal Server Error - Something went wrong with the DoiT API server.