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 required
Possible values: [ANY, TCP, UDP, ICMP]
description string
Possible values: <= 255 characters
allowedRoleID string nullable
Role ID to allow with this firewall rule. If not specified, all roles are included.
allowedTags key:value[]
Tags to allow with this firewall rule. An empty list allows all tags. key is max 20 characters, value is max 50 characters, no whitespace around either allowed
portRange object nullable
Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.
from integer required
Possible values: >= 1 and <= 65535
First port number included in range.
to integer required
Possible values: >= 1 and <= 65535
Last port number included in range. Must be greater than from port.
]

Responses

Successful operation

application/json

Schema
Example (from schema)

Schema

data object
id string
name string
description string
firewallRules object[]
Array [
protocol string required
Possible values: [ANY, TCP, UDP, ICMP]
description string
Possible values: <= 255 characters
allowedRoleID string nullable
Role ID to allow with this firewall rule. If not specified, all roles are included.
allowedTags key:value[]
Tags to allow with this firewall rule. An empty list allows all tags. key is max 20 characters, value is max 50 characters, no whitespace around either allowed
portRange object nullable
Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.
from integer required
Possible values: >= 1 and <= 65535
First port number included in range.
to integer required
Possible values: >= 1 and <= 65535
Last port number included in range. Must be greater than from port.
]
createdAt date-time
modifiedAt 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

errors object[] required
Array [
code string required
A static name for the error type
message string required
A short human readable description of the error
path string nullable
Describes 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"
    }
  ]
}

Create role

Request​

Request