Create custom role
POST
/api/v1/organizations/{orgId}/roles
const url = 'http://localhost:3000/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/roles';const options = { method: 'POST', headers: {'X-API-Key': '<X-API-Key>', 'Content-Type': 'application/json'}, body: '{"name":"Device Operator","description":"Can view and manage devices but not deployments","permissions":["devices:read","devices:write","deployments:read"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:3000/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/roles \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <X-API-Key>' \ --data '{ "name": "Device Operator", "description": "Can view and manage devices but not deployments", "permissions": [ "devices:read", "devices:write", "deployments:read" ] }'Creates a new custom role for the organization.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ” orgId
required
string format: uuid
Organization UUID
Request Body required
Section titled “Request Body required ” Media type application/json
object
name
required
Role display name
string
Example
Device Operator description
Role description
string
Example
Can view and manage devices but not deployments permissions
required
List of permission keys assigned to this role
Array<string>
Example
[ "devices:read", "devices:write", "deployments:read"]Responses
Section titled “ Responses ”Role created successfully
Media type application/json
object
id
required
Unique role identifier
string format: uuid
name
required
Role display name
string
description
Role description
string
permissions
required
List of permission keys assigned to this role
Array<string>
isSystem
required
Whether this is a system-defined role (cannot be modified)
boolean
organizationId
Organization ID (null for system roles)
string format: uuid
createdAt
required
When the role was created
string format: date-time
updatedAt
required
When the role was last updated
string format: date-time
Example
{ "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Device Operator", "description": "Can view and manage devices but not deployments", "permissions": [ "devices:read", "devices:write", "deployments:read" ], "isSystem": false, "organizationId": "550e8400-e29b-41d4-a716-446655440001", "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-06-20T14:45:00Z"}Invalid input data
Unauthorized
Forbidden - Insufficient permissions
Role with this name already exists