Create role

POST 
/v1/roles

Create a new role.

Token scope required: roles:create

Request

application/json

Body

required

name stringrequired

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 stringrequired

Possible values: [ANY, TCP, UDP, ICMP]

description string

Possible values: <= 255 characters

allowedRoleID stringnullable

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 integerrequired

Possible values: >= 1 and <= 65535

First port number included in range.

to integerrequired

Possible values: >= 1 and <= 65535

Last port number included in range. Must be greater than from port.

]

Responses

200

Successful operation

application/json

Schema

Schema

data

object

id string

name string

description string

firewallRules

object[]

Array [

protocol stringrequired

Possible values: [ANY, TCP, UDP, ICMP]

description string

Possible values: <= 255 characters

allowedRoleID stringnullable

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 integerrequired

Possible values: >= 1 and <= 65535

First port number included in range.

to integerrequired

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

Example (from schema)

{
  "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": {}
}

400

Validation error

application/json

Schema

Schema

errors

object[]

required

Array [

code stringrequired

A static name for the error type

message stringrequired

A short human readable description of the error

path stringnullable

Describes the variable missing or malformed

]

Example (from schema)

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "path": "string"
    }
  ]
}

missingName

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE_LENGTH",
      "message": "must have a length between 1 and 50",
      "path": "name"
    }
  ]
}

duplicateName

{
  "errors": [
    {
      "code": "ERR_DUPLICATE_VALUE",
      "message": "value already exists",
      "path": "name"
    }
  ]
}

protocol

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "must be a valid protocol: ANY, TCP, UDP, ICMP",
      "path": "firewallRules[0].protocol"
    }
  ]
}

portRangeMissing

{
  "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"
    }
  ]
}

portRangeOrder

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "from must be less than or equal to to",
      "path": "firewallRules[0].portRange"
    }
  ]
}

Loading...