Create role
POST /v1/roles
Create a new role.
Token scope required: roles:create
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
Name of the new role
Example
My new roleOptional description
Incoming firewall rules
object
One of ANY, TCP, UDP or ICMP when creating or updating a rule. Responses may include protocols added later, so clients should accept values not listed here.
Role ID to allow with this firewall rule. If not specified, all roles are included.
Tags to allow with this firewall rule. An empty list allows all tags; responses return null instead of an empty list. key is max 20 characters, value is max 50 characters, no whitespace around either allowed
Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.
object
First port number included in range.
Last port number included in range. Must be greater than from port.
Responses
Section titled “ Responses ”Successful operation
object
object
object
One of ANY, TCP, UDP or ICMP when creating or updating a rule. Responses may include protocols added later, so clients should accept values not listed here.
Role ID to allow with this firewall rule. If not specified, all roles are included.
Tags to allow with this firewall rule. An empty list allows all tags; responses return null instead of an empty list. key is max 20 characters, value is max 50 characters, no whitespace around either allowed
Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.
object
First port number included in range.
Last port number included in range. Must be greater than from port.
Number of hosts currently assigned to this role.
Example
{ "data": { "id": "role-LO4SPDSWTZNJC676WFCZKUB3ZQ", "name": "My new role", "description": "", "hostCount": 0, "createdAt": "2023-02-15T13:59:09Z", "modifiedAt": "2023-02-15T13:59:09Z", "firewallRules": [ { "protocol": "TCP", "description": "allow SSH access", "allowedRoleID": "role-G3TWUQ4FASQEF44MGMTSRBTYKM", "allowedTags": null, "portRange": { "from": 22, "to": 22 } } ] }}Validation error
object
object
A static name for the error type
A short human readable description of the error
Describes the variable missing or malformed
The query parameter the error relates to, such as filter.targetType
Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.
object
The maximum number of resources allowed
The kind of resource the limit applies to
Examples
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" } ]}allowedRoleID does not exist.
{ "errors": [ { "code": "ERR_INVALID_REFERENCE", "message": "referenced value is invalid (perhaps it does not exist?)", "path": "firewallRules[0].allowedRoleID" } ]}The API key is missing, invalid or expired.
object
object
A static name for the error type
A short human readable description of the error
Describes the variable missing or malformed
The query parameter the error relates to, such as filter.targetType
Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.
object
The maximum number of resources allowed
The kind of resource the limit applies to
Example
{ "errors": [ { "code": "ERR_UNAUTHORIZED", "message": "unauthorized" } ]}The API key lacks a required scope.
object
object
A static name for the error type
A short human readable description of the error
Describes the variable missing or malformed
The query parameter the error relates to, such as filter.targetType
Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.
object
The maximum number of resources allowed
The kind of resource the limit applies to
Examples
The API key lacks a required scope.
{ "errors": [ { "code": "ERR_FORBIDDEN", "message": "api key must support the following scopes: hosts:read" } ]}The organization has exceeded its API request rate limit. Retry the request after a short delay.
object
object
A static name for the error type
A short human readable description of the error
Describes the variable missing or malformed
The query parameter the error relates to, such as filter.targetType
Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.
object
The maximum number of resources allowed
The kind of resource the limit applies to
Example
{ "errors": [ { "code": "ERR_TOO_MANY_REQUESTS", "message": "too many requests" } ]}