IAM API

Manage Identity and Access Management roles and their CASL policy statements. Role management requires Super Admin (manage:all) permission. Reading roles requires read:roles permission.

List All Roles

List all roles

GET

/v1/iam/roles

Returns all IAM roles. If predefined roles do not yet exist, they are created automatically. Requires read:roles permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Responses

List of roles.

Content-Type

application/json

[

  

{

  

  

"id": "clx1y2z3a0000b4d2",

  

  

"slug": "predefined_super_admin",

  

  

"name": "Super Admin",

  

  

"policies": [

  

  

  

{

  

  

  

  

"action": "read",

  

  

  

  

"subject": "archive",

  

  

  

  

"conditions": {

  

  

  

  

}

  

  

  

}

  

  

],

  

  

"createdAt": "string",

  

  

"updatedAt": "string"

  

}

]

GET

/v1/iam/roles

Playground

Authorization

bearerAuth

Samples

Powered by VitePress OpenAPI

Create a Role

Create a role

POST

/v1/iam/roles

Creates a new IAM role with the given name and CASL policies. Requires manage:all (Super Admin) permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Request Body

application/json

{

  

"name": "Compliance Officer",

  

"policies": [

  

  

{

  

  

  

"action": "read",

  

  

  

"subject": "archive",

  

  

  

"conditions": {

  

  

  

}

  

  

}

  

]

}

Responses

Role created.

Content-Type

application/json

{

  

"id": "clx1y2z3a0000b4d2",

  

"slug": "predefined_super_admin",

  

"name": "Super Admin",

  

"policies": [

  

  

{

  

  

  

"action": "read",

  

  

  

"subject": "archive",

  

  

  

"conditions": {

  

  

  

}

  

  

}

  

],

  

"createdAt": "string",

  

"updatedAt": "string"

}

POST

/v1/iam/roles

Playground

Authorization

bearerAuth

Body

Samples

Powered by VitePress OpenAPI

Get a Role

Get a role

GET

/v1/iam/roles/{id}

Returns a single IAM role by ID. Requires read:roles permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Parameters

Path Parameters

id*

Type

string

Required

Example"clx1y2z3a0000b4d2"

Responses

Role details.

Content-Type

application/json

{

  

"id": "clx1y2z3a0000b4d2",

  

"slug": "predefined_super_admin",

  

"name": "Super Admin",

  

"policies": [

  

  

{

  

  

  

"action": "read",

  

  

  

"subject": "archive",

  

  

  

"conditions": {

  

  

  

}

  

  

}

  

],

  

"createdAt": "string",

  

"updatedAt": "string"

}

GET

/v1/iam/roles/{id}

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

Powered by VitePress OpenAPI

Update a Role

Update a role

PUT

/v1/iam/roles/{id}

Updates the name or policies of an IAM role. Requires manage:all (Super Admin) permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Parameters

Path Parameters

id*

Type

string

Required

Example"clx1y2z3a0000b4d2"

Request Body

application/json

{

  

"name": "Senior Compliance Officer",

  

"policies": [

  

  

{

  

  

  

"action": "read",

  

  

  

"subject": "archive",

  

  

  

"conditions": {

  

  

  

}

  

  

}

  

]

}

Responses

Updated role.

Content-Type

application/json

{

  

"id": "clx1y2z3a0000b4d2",

  

"slug": "predefined_super_admin",

  

"name": "Super Admin",

  

"policies": [

  

  

{

  

  

  

"action": "read",

  

  

  

"subject": "archive",

  

  

  

"conditions": {

  

  

  

}

  

  

}

  

],

  

"createdAt": "string",

  

"updatedAt": "string"

}

PUT

/v1/iam/roles/{id}

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Body

Samples

Powered by VitePress OpenAPI

Delete a Role

Delete a role

DELETE

/v1/iam/roles/{id}

Permanently deletes an IAM role. Requires manage:all (Super Admin) permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Parameters

Path Parameters

id*

Type

string

Required

Example"clx1y2z3a0000b4d2"

Responses

Role deleted. No content returned.

DELETE

/v1/iam/roles/{id}

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

Powered by VitePress OpenAPI