Edit role
PUT /v1/roles/{roleID}
Token scope required: roles:update
Caution: Any properties not provided in the request will be reset to their default values. If only changing one firewall rule, be sure to include the others as well, otherwise they will be removed.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Example
role-LO4SPDSWTZNJC676WFCZKUB3ZQRequest Body required
Section titled “Request Body required ”object
Incoming firewall rules. Will replace existing list of 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
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" } ]}Role not found
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_NOT_FOUND", "message": "resource not found" } ]}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" } ]}