Create role
POST /v1/roles
Create a new role.
Token scope required: roles:create
Request
- application/json
Request Body required
- name string required
Possible values:
non-empty
and<= 50 characters
Name of the new role
- description string
Possible values:
<= 255 characters
Optional description
firewallRules object[]
Incoming firewall rules
Array [protocol string requiredPossible values: [
ANY
,TCP
,UDP
,ICMP
]description stringPossible values:
<= 255 characters
allowedRoleID stringRole ID to allow with this firewall rule. If not specified, all roles are included.
portRange object
Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.
from integer requiredPossible values:
>= 1
and<= 65535
First port number included in range.
to integer requiredPossible values:
>= 1
and<= 65535
Last port number included in range. Must be greater than
from
port.]
- 200
- 400
Successful operation
- application/json
- Schema
- Example (from schema)
Schema
data object
id stringname stringdescription stringfirewallRules object[]
Array [protocol string requiredPossible values: [
ANY
,TCP
,UDP
,ICMP
]description stringPossible values:
<= 255 characters
allowedRoleID stringRole ID to allow with this firewall rule. If not specified, all roles are included.
portRange object
Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.
from integer requiredPossible values:
>= 1
and<= 65535
First port number included in range.
to integer requiredPossible values:
>= 1
and<= 65535
Last port number included in range. Must be greater than
from
port.]createdAt date-timemodifiedAt date-time- metadata object
{
"data": {
"id": "role-LO4SPDSWTZNJC676WFCZKUB3ZQ",
"name": "My new role",
"description": "",
"createdAt": "2023-02-15T13:59:09Z",
"modifiedAt": "2023-02-15T13:59:09Z",
"firewallRules": [
{
"protocol": "TCP",
"description": "allow SSH access",
"allowedRoleID": "role-G3TWUQ4FASQEF44MGMTSRBTYKM",
"portRange": {
"from": 22,
"to": 22
}
}
]
},
"metadata": {}
}
Validation error
- application/json
- Schema
- Example (from schema)
- missingName
- duplicateName
- protocol
- portRangeMissing
- portRangeOrder
Schema
errors object[] required
Array [code string requiredA static name for the error type
message string requiredA short human readable description of the error
path string nullableDescribes the variable missing or malformed
]
{
"errors": [
{
"code": "string",
"message": "string",
"path": "string"
}
]
}
name
not specified.
{
"errors": [
{
"code": "ERR_INVALID_VALUE_LENGTH",
"message": "must have a length between 1 and 50",
"path": "name"
}
]
}
A role with the name already exists.
{
"errors": [
{
"code": "ERR_DUPLICATE_VALUE",
"message": "value already exists",
"path": "name"
}
]
}
Invalid protocol
value.
{
"errors": [
{
"code": "ERR_INVALID_VALUE",
"message": "must be a valid protocol: ANY, TCP, UDP, ICMP",
"path": "firewallRules[0].protocol"
}
]
}
Invalid/missing from
and to
values.
{
"errors": [
{
"code": "ERR_INVALID_VALUE",
"message": "must be between 1 and 65535",
"path": "firewallRules[0].portRange.from"
},
{
"code": "ERR_INVALID_VALUE",
"message": "must be between 1 and 65535",
"path": "firewallRules[0].portRange.to"
}
]
}
From
cannot be greater than to
{
"errors": [
{
"code": "ERR_INVALID_VALUE",
"message": "from must be less than or equal to to",
"path": "firewallRules[0].portRange"
}
]
}