Server Groups

The Server Groups resource provides access to all methods relating to Server Groups management in Keystash. Server Groups are logical groups of servers to allow for quick and easy bulk management of User privileges and SSH service policy.

List Server Groups

Path: `/server-groups/list`

Method: `GET`

Authentication: `Bearer Token`

Request Headers

Key	Value	Required
`Accept-Encoding`	gzip	optional

Request Parameters

None.

Request Body

None.

Example Request

curl --location --request GET 'https://app.keystash.io/api/v1/server-groups/list' \
--header 'Authorization: Bearer <token>'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "id": "Gfz5m9mGuIp6ByPz",
    "name": "Production Servers",
    "description": "All production servers.",
    "version": 117,
    "default_group": true,
    "password_auth_enabled": true,
    "two_factor_enabled": false,
    "two_factor_disallow_reuse": true,
    "two_factor_window_size": 1,
    "two_factor_rate_limit": 3,
    "created": "2022-04-03 16:03:42",
    "created_user_id": "x0Uf09z8TYjoNVFB",
    "created_by": "Max Smith",
    "modified": "2023-09-25 07:28:22",
    "modified_user_id": "x0Uf09z8TYjoNVFB",
    "modified_by": "Max Smith"
  },
  {
    "id": "rzbSZtL2zI0oA16V",
    "name": "Production Databases",
    "description": "",
    "version": 85,
    "default_group": false,
    "password_auth_enabled": false,
    "two_factor_enabled": true,
    "two_factor_disallow_reuse": true,
    "two_factor_window_size": 2,
    "two_factor_rate_limit": 3,
    "created": "2022-05-25 12:22:41",
    "created_user_id": "x0Uf09z8TYjoNVFB",
    "created_by": "Max Smith",
    "modified": "2023-09-25 07:28:22",
    "modified_user_id": "x0Uf09z8TYjoNVFB",
    "modified_by": "Max Smith"
  }
]

Example Error Response

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "Your request was successfully processed but there was no data to be returned.",
    "details": []
  }
}

View Server Group

Path: `/server-groups/view`

Method: `GET`

Authentication: `Bearer Token`

Request Headers

Key	Value	Required
`Accept-Encoding`	gzip	optional

Request Parameters

Key	Data Type	Required	Notes
`id`	string	required	The ID of the server group to view

Request Body

None.

Example Request

curl --location --request GET 'https://app.keystash.io/api/v1/server-groups/view?id=BD720EP87kNORRcH' \
--header 'Authorization: Bearer <token>'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "BD720EP87kNORRcH",
  "name": "Production Databases",
  "description": "",
  "version": 633,
  "default_group": true,
  "password_auth_enabled": false,
  "two_factor_enabled": true,
  "two_factor_disallow_reuse": true,
  "two_factor_window_size": 1,
  "two_factor_rate_limit": 3,
  "created": "2021-01-09 19:10:47",
  "created_user_id": "bkQV8I5BRcAVpgod",
  "created_by": "Max Smith",
  "modified": "2024-05-21 14:19:47",
  "modified_user_id": "bkQV8I5BRcAVpgod",
  "modified_by": "Max Smith"
}

Example Error Response

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "Your request was successfully processed but there was no data to be returned.",
    "details": []
  }
}

Create Server Group

Path: `/server-groups/create`

Method: `POST`

Authentication: `Bearer Token`

Request Headers

Key	Value	Required
`Content-Type`	`application/json`	required

Request Parameters

None.

Request Body Parameters

Key	Data Type	Required	Notes
`name`	string	required	The name of the server group
`description`	string	optional	Description of the server group
`password_auth_enabled`	boolean	required	Whether password authentication is enabled. Note: Cannot be set to true if `two_factor_enabled` is true.
`two_factor_enabled`	boolean	required	Whether two-factor authentication is enabled. Note: Cannot be set to true if `password_auth_enabled` is true.
`two_factor_disallow_reuse`	boolean	required	Whether to allow Two Factor codes to be used more than once. This option determines if you are able to use a Two Factor 6 Digit pin more than once in a 30 second window. For example: If you open two SSH connections to the same server in short succession you would be prompted for a Two Factor Authentication 6 digit pin. If you entered in the pin on the first SSH session you would have to wait for a new 6 digit pin to generate before you could login on the second connection. Disabling this option allows you to use the same 6 digit pin two or more times in quick succession. We suggest enabling this for increased security.
`two_factor_window_size`	integer	optional	Allowance for time difference between server and your mobile phone - As Keystash uses the TOTP algorithm it is important to ensure that all servers using SSH Two Factor Authentication have a reliable NTP source. This is so that all your users mobile phones and all the servers have the correct date and time. Large differences (over 2 minutes) can cause issues during SSH Two Factor Authentication. To help combat these issues you can allow for medium (75 seconds) and large (130 seconds) differences between the servers clocks and the mobile phones clocks. Normal is considered the most secure but is the most strict. The available options for this setting are: 1 = Normal, 2 = Medium and 3 = Large. Defaults to 1 (Normal) if not provided.
`two_factor_rate_limit`	integer	optional	The rate limit for two-factor authentication attempts. Available options are: 1,2,3 or 4. 1 = (Off) No rate limiting. 2 = (Permissive) 10 logins every 30 seconds per user account. 3 = (Normal) 3 logins every 30 seconds per user account. 4 = (Restrictive) 1 login every 30 seconds per user account. Defaults to 3 (Normal) if not provided.

Example Request Body

{
    "name": "My Group",
    "description": "My Group of servers",
    "password_auth_enabled": false,
    "two_factor_enabled": true,
    "two_factor_disallow_reuse": true,
    "two_factor_window_size": 3,
    "two_factor_rate_limit": 2
}

Example Request

curl --location --request POST 'https://app.keystash.io/api/v1/server-groups/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
    "name": "My Group",
    "description": "My Group of servers",
    "password_auth_enabled": false,
    "two_factor_enabled": true,
    "two_factor_disallow_reuse": true,
    "two_factor_window_size": 3,
    "two_factor_rate_limit": 2
}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "result": "Server Group was successfully created.",
    "id": "BD720EP87kNORRcH"
}

Example Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
    "error": {
        "code": "BadArgument",
        "message": "There was a problem with one or more arguments in your request. Please check your request and resubmit.",
        "details": [
            {
                "field": "name",
                "message": "name is a required field and cannot be empty."
            }
        ]
    }
}

Set Default Server Group

Path: `/server-groups/set-default`

Method: `POST`

Authentication: `Bearer Token`

Request Headers

Key	Value	Required
`Content-Type`	`application/json`	required

Request Parameters

None.

Request Body Parameters

Key	Data Type	Required	Notes
`id`	string	required	The ID of the server group to set as default

Example Request Body

{
    "id": "BD720EP87kNORRcH"
}

Example Request

curl --location --request POST 'https://app.keystash.io/api/v1/server-groups/set-default' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
    "id": "BD720EP87kNORRcH"
}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "Server Group with ID BD720EP87kNORRcH was successfully updated."
}

Example Error Response

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "Your request was successfully processed but there was no data to be returned.",
    "details": []
  }
}

Update Server Group

Path: `/server-groups/update`

Method: `PATCH`

Authentication: `Bearer Token`

Request Headers

Key	Value	Required
`Content-Type`	`application/json`	required

Request Parameters

None.

Request Body Parameters

Key	Data Type	Required	Notes
`id`	string	required	The ID of the server group to update
`name`	string	optional	The name of the server group
`description`	string	optional	Description of the server group
`password_auth_enabled`	boolean	required	Whether password authentication is enabled. Note: Cannot be set to true if `two_factor_enabled` is true.
`two_factor_enabled`	boolean	required	Whether two-factor authentication is enabled. Note: Cannot be set to true if `password_auth_enabled` is true.
`two_factor_disallow_reuse`	boolean	required	Whether to allow Two Factor codes to be used more than once. This option determines if you are able to use a Two Factor 6 Digit pin more than once in a 30 second window. For example: If you open two SSH connections to the same server in short succession you would be prompted for a Two Factor Authentication 6 digit pin. If you entered in the pin on the first SSH session you would have to wait for a new 6 digit pin to generate before you could login on the second connection. Disabling this option allows you to use the same 6 digit pin two or more times in quick succession. We suggest enabling this for increased security.
`two_factor_window_size`	integer	optional	Allowance for time difference between server and your mobile phone - As Keystash uses the TOTP algorithm it is important to ensure that all servers using SSH Two Factor Authentication have a reliable NTP source. This is so that all your users mobile phones and all the servers have the correct date and time. Large differences (over 2 minutes) can cause issues during SSH Two Factor Authentication. To help combat these issues you can allow for medium (75 seconds) and large (130 seconds) differences between the servers clocks and the mobile phones clocks. Normal is considered the most secure but is the most strict. The available options for this setting are: 1 = Normal, 2 = Medium and 3 = Large. Defaults to 1 (Normal) if not provided.
`two_factor_rate_limit`	integer	optional	The rate limit for two-factor authentication attempts. Available options are: 1,2,3 or 4. 1 = (Off) No rate limiting. 2 = (Permissive) 10 logins every 30 seconds per user account. 3 = (Normal) 3 logins every 30 seconds per user account. 4 = (Restrictive) 1 login every 30 seconds per user account. Defaults to 3 (Normal) if not provided.

Example Request Body

{
    "id": "BD720EP87kNORRcH",
    "name": "API Test Group",
    "description": "New description.",
    "two_factor_window_size": 1,
    "two_factor_rate_limit": 1
}

Example Request

curl --location --request PATCH 'https://app.keystash.io/api/v1/server-groups/update' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
    "id": "BD720EP87kNORRcH",
    "name": "API Test Group",
    "description": "New description.",
    "two_factor_window_size": 1,
    "two_factor_rate_limit": 1
}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "Server Group with ID BD720EP87kNORRcH was successfully updated."
}

Example Error Response

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "Your request was successfully processed but there was no data to be returned.",
    "details": []
  }
}

Delete Server Group

Path: `/server-groups/delete`

Method: `DELETE`

Authentication: `Bearer Token`

Request Headers

Key	Value	Required
`Accept-Encoding`	gzip	optional

Request Parameters

Key	Data Type	Required	Notes
`id`	string	required	The ID of the server group to delete

Request Body

None.

Example Request

curl --location --request DELETE 'https://app.keystash.io/api/v1/server-groups/delete?id=BD720EP87kNORRcH' \
--header 'Authorization: Bearer <token>'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "Server Group with ID BD720EP87kNORRcH was successfully deleted."
}

Example Error Response

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "Your request was successfully processed but there was no data to be returned.",
    "details": []
  }
}

List Users in Server Group

Path: `/server-groups/list-users`

Method: `GET`

Authentication: `Bearer Token`

Request Headers

Key	Value	Required
`Accept-Encoding`	gzip	optional

Request Parameters

Key	Data Type	Required	Notes
`id`	string	required	The ID of the server group whose users are to be listed

Request Body

None.

Example Request

curl --location --request GET 'https://app.keystash.io/api/v1/server-groups/list-users?id=BD720EP87kNORRcH' \
--header 'Authorization: Bearer <token>'

Response Fields

Field	Data Type	Description
`user_id`	string	The unique ID of the user
`firstname`	string	The user's first name
`lastname`	string	The user's last name
`server_username`	string	The username used on servers for this user
`email`	string	The user's email address
`permission_level`	string	The effective permission level for this user in the server group. Possible values: "Root", "User", "Disabled"
`override_groups`	boolean	Indicates whether the user has individual permission settings that override inherited settings from User Groups
`permission_level_inherited`	boolean	Indicates whether the user's permission level is inherited from User Groups. When `true` and `override_groups` is `false`, the permission level comes from User Group membership
`linux_groups_inherited`	boolean	Indicates whether the user's Linux groups are inherited from User Groups. When `true` and `override_groups` is `false`, the Linux groups come from User Group membership
`linux_groups`	array	Array of Linux group objects assigned to the user. Each object contains `id` (the Linux group's ID) and `name` (the Linux group's name)

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "user_id": "bkQV8I5BRcAVpgod",
    "firstname": "Max",
    "lastname": "Smith",
    "server_username": "maxsmith",
    "email": "max.smith@example.org",
    "permission_level": "Root",
    "override_groups": false,
    "permission_level_inherited": false,
    "linux_groups_inherited": false,
    "linux_groups": [
      {
        "id": "Gfz5m9mGuIp6ByPz",
        "name": "developers"
      },
      {
        "id": "rzbSZtL2zI0oA16V",
        "name": "admins"
      }
    ]
  },
  {
    "user_id": "t2er3Mo68eFWMbVk",
    "firstname": "Anne",
    "lastname": "Teak",
    "server_username": "anneteak",
    "email": "anne.teak@example.org",
    "permission_level": "User",
    "override_groups": false,
    "permission_level_inherited": true,
    "linux_groups_inherited": true,
    "linux_groups": [
      {
        "id": "Gfz5m9mGuIp6ByPz",
        "name": "developers"
      }
    ]
  },
  {
    "user_id": "ZaPkEfpPIlhKv3eO",
    "firstname": "Perry",
    "lastname": "Scope",
    "server_username": "perryscope",
    "email": "perry.scope@example.org",
    "permission_level": "Disabled",
    "override_groups": true,
    "permission_level_inherited": false,
    "linux_groups_inherited": false,
    "linux_groups": []
  }
]

Example Error Response

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "Your request was successfully processed but there was no data to be returned.",
    "details": []
  }
}

Update User in Server Group

Path: `/server-groups/update-user`

Method: `PATCH`

Authentication: `Bearer Token`

Request Headers

Key	Value	Required
`Content-Type`	`application/json`	required

Request Parameters

None

Request Body Parameters

Key	Data Type	Required	Notes
`server_group_id`	string	required	The ID of the server group
`user_id`	string	required	The ID of the user to update
`permission_level`	string	required	The new permission level for the user. Options are "Disabled", "User" and "Root".
`override_groups`	boolean	optional	Whether to override inherited settings from User Groups. When `true`, the user's individual permission and Linux group settings take precedence over those inherited from User Groups. When `false` or not provided, settings are inherited from User Groups. Defaults to `false`.
`linux_group_ids`	array	optional	Array of Linux group IDs to assign to the user in this server group. Each element should be a string containing a valid Linux group ID. If not provided, existing Linux group assignments remain unchanged.
`linux_groups`	array	optional	Array of Linux group objects with IDs to assign to the user in this server group. Each element should be an object containing a valid Linux group ID. If not provided, existing Linux group assignments remain unchanged.
Note			You should only provide `linux_group_ids` OR `linux_groups`, never both. The system will always prioritise and use `linux_group_ids` over `linux_groups`. `linux_groups` is proivded as a convenience field allowing users to copy `linux_groups` from the response provided by `/server-groups/list-users` API endpoint.

Example Request Body

{
    "server_group_id": "BD720EP87kNORRcH",
    "user_id": "bkQV8I5BRcAVpgod",
    "permission_level": "User",
    "override_groups": true,
    "linux_group_ids": ["Gfz5m9mGuIp6ByPz", "rzbSZtL2zI0oA16V"],
    "linux_groups": [{"id": "Gfz5m9mGuIp6ByPz"}, {"id": "rzbSZtL2zI0oA16V"}]
}

Example Request

curl --location --request PATCH 'https://app.keystash.io/api/v1/server-groups/update-user' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
    "server_group_id": "BD720EP87kNORRcH",
    "user_id": "bkQV8I5BRcAVpgod",
    "permission_level": "User",
    "override_groups": true,
    "linux_group_ids": ["Gfz5m9mGuIp6ByPz", "rzbSZtL2zI0oA16V"]
}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "Server Group with ID BD720EP87kNORRcH was successfully updated."
}

Example Error Response

Missing Required Parameters (400 Bad Request)

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "BadArgument",
    "message": "There was a problem with one or more arguments in your request. Please check your request and resubmit.",
    "details": [
      "The following required parameters are missing from your request: server_group_id, user_id"
    ]
  }
}

Invalid Permission Level (400 Bad Request)

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "BadArgument",
    "message": "There was a problem with one or more arguments in your request. Please check your request and resubmit.",
    "details": [
      "Invalid permission level provided. Valid options are: Root, User, Disabled"
    ]
  }
}

User Not Found (404 Not Found)

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "There was a problem with one or more arguments in your request. Please check your request and resubmit.",
    "details": [
      "Could not find a User for the User ID provided."
    ]
  }
}

Server Group Not Found (404 Not Found)

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "There was a problem with one or more arguments in your request. Please check your request and resubmit.",
    "details": [
      "Could not find a Server Group for the Server Group ID provided."
    ]
  }
}

Linux Groups Not Found (404 Not Found)

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "There was a problem with one or more arguments in your request. Please check your request and resubmit.",
    "details": [
      "Could not find Linux Groups with IDs: xyz123abc456"
    ]
  }
}

Database Save Error (500 Internal Server Error)

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "DataSaveError",
    "message": "There was a system problem while saving data to the database.",
    "details": []
  }
}

List User Groups in Server Group

Path: `/server-groups/list-user-groups`

Method: `GET`

Authentication: `Bearer Token`

Request Headers

Key	Value	Required
`Accept-Encoding`	gzip	optional

Request Parameters

Key	Data Type	Required	Notes
`id`	string	required	The ID of the server group whose user groups are to be listed

Request Body

None.

Example Request

curl --location --request GET 'https://app.keystash.io/api/v1/server-groups/list-user-groups?id=BD720EP87kNORRcH' \
--header 'Authorization: Bearer <token>'

Response Fields

Field	Data Type	Description
`user_group_id`	string	The unique ID of the user group
`name`	string	The user group's name
`description`	string	The user group's description
`permission_level`	string	The permission level for this user group in the server group. Possible values: "Root", "User", "Disabled", "Not Set"
`user_count`	integer	The number of users in the user group
`linux_groups`	array	Array of Linux group objects assigned to the user group in this server group. Each object contains `id` (the Linux group's ID) and `name` (the Linux group's name)

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "user_group_id": "p3Km8NxLtYqR9wZd",
    "name": "Development Team",
    "description": "Development team user group",
    "permission_level": "Root",
    "user_count": 5,
    "linux_groups": [
      {
        "id": "Gfz5m9mGuIp6ByPz",
        "name": "developers"
      },
      {
        "id": "rzbSZtL2zI0oA16V",
        "name": "admins"
      }
    ]
  },
  {
    "user_group_id": "v7QxRm2NhPzF4jLk",
    "name": "Operations Team",
    "description": "Operations and infrastructure team",
    "permission_level": "User",
    "user_count": 3,
    "linux_groups": [
      {
        "id": "Gfz5m9mGuIp6ByPz",
        "name": "developers"
      }
    ]
  },
  {
    "user_group_id": "n9TwYp5MkBvD8xRh",
    "name": "Contractors",
    "description": "",
    "permission_level": "Disabled",
    "user_count": 2,
    "linux_groups": []
  }
]

Example Error Response

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "Your request was successfully processed but there was no data to be returned.",
    "details": []
  }
}

Update User Group in Server Group

Path: `/server-groups/update-user-group`

Method: `PATCH`

Authentication: `Bearer Token`

Request Headers

Key	Value	Required
`Content-Type`	`application/json`	required

Request Parameters

None

Request Body Parameters

Key	Data Type	Required	Notes
`server_group_id`	string	required	The ID of the server group
`user_group_id`	string	required	The ID of the user group to update
`permission_level`	string	required	The permission level for the user group. Options are "Disabled", "User", "Root", or "Unset". Setting to "Unset" removes the user group's permissions from the server group. Note: Cannot set to "Unset" if the user group does not currently have permissions for this server group.
`linux_group_ids`	array	optional	Array of Linux group IDs to assign to the user group in this server group. Each element should be a string containing a valid Linux group ID. If not provided, existing Linux group assignments remain unchanged.
`linux_groups`	array	optional	Array of Linux group objects with IDs to assign to the user group in this server group. Each element should be an object containing a valid Linux group ID. If not provided, existing Linux group assignments remain unchanged.
Note			You should only provide `linux_group_ids` OR `linux_groups`, never both. The system will always prioritise and use `linux_group_ids` over `linux_groups`. `linux_groups` is proivded as a convenience field allowing users to copy `linux_groups` from the response provided by `/server-groups/list-users` API endpoint.

Example Request Body

{
    "server_group_id": "BD720EP87kNORRcH",
    "user_group_id": "p3Km8NxLtYqR9wZd",
    "permission_level": "Root",
    "linux_group_ids": ["Gfz5m9mGuIp6ByPz", "rzbSZtL2zI0oA16V"]
}

Example Request

curl --location --request PATCH 'https://app.keystash.io/api/v1/server-groups/update-user-group' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
    "server_group_id": "BD720EP87kNORRcH",
    "user_group_id": "p3Km8NxLtYqR9wZd",
    "permission_level": "Root",
    "linux_group_ids": ["Gfz5m9mGuIp6ByPz", "rzbSZtL2zI0oA16V"]
}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "Server Group with ID BD720EP87kNORRcH was successfully updated."
}

Example Error Response

Missing Required Parameters (400 Bad Request)

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "BadArgument",
    "message": "There was a problem with one or more arguments in your request. Please check your request and resubmit.",
    "details": [
      "The following required parameters are missing from your request: server_group_id, user_group_id"
    ]
  }
}

Invalid Permission Level (400 Bad Request)

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "BadArgument",
    "message": "There was a problem with one or more arguments in your request. Please check your request and resubmit.",
    "details": [
      {
        "field": "permission_level",
        "validation": "value",
        "message": "The permission_level must be a string set to 'Disabled', 'User', 'Root' or 'Unset'."
      }
    ]
  }
}

Cannot Unset Non-Existent Permission (400 Bad Request)

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "BadArgument",
    "message": "Cannot unset a permission that does not exist. The User Group does not currently have any permissions for this Server Group.",
    "details": []
  }
}

User Group Not Found (404 Not Found)

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "There was a problem with one or more arguments in your request. Please check your request and resubmit.",
    "details": [
      "Could not find a User Group for the User Group ID provided."
    ]
  }
}

Server Group Not Found (404 Not Found)

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "There was a problem with one or more arguments in your request. Please check your request and resubmit.",
    "details": [
      "Could not find a Server Group for the Server Group ID provided."
    ]
  }
}

Linux Groups Not Found (404 Not Found)

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "NotFound",
    "message": "There was a problem with one or more arguments in your request. Please check your request and resubmit.",
    "details": [
      "Could not find Linux Groups with IDs: xyz123abc456"
    ]
  }
}

Database Save Error (500 Internal Server Error)

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "DataSaveError",
    "message": "There was a system problem while saving data to the database.",
    "details": []
  }
}

Server Groups

List Server Groups

Path: /server-groups/list

Method: GET

Authentication: Bearer Token

Request Headers

Request Parameters

Request Body

Example Request

Example Response

Example Error Response

View Server Group

Path: /server-groups/view

Method: GET

Authentication: Bearer Token

Request Headers

Request Parameters

Request Body

Example Request

Example Response

Example Error Response

Create Server Group

Path: /server-groups/create

Method: POST

Authentication: Bearer Token

Request Headers

Request Parameters

Request Body Parameters

Example Request Body

Example Request

Example Response

Example Error Response

Set Default Server Group

Path: /server-groups/set-default

Method: POST

Authentication: Bearer Token

Request Headers

Request Parameters

Request Body Parameters

Example Request Body

Example Request

Example Response

Example Error Response

Update Server Group

Path: /server-groups/update

Method: PATCH

Authentication: Bearer Token

Request Headers

Request Parameters

Request Body Parameters

Example Request Body

Example Request

Example Response

Example Error Response

Delete Server Group

Path: /server-groups/delete

Method: DELETE

Authentication: Bearer Token

Request Headers

Request Parameters

Request Body

Example Request

Example Response

Example Error Response

List Users in Server Group

Path: /server-groups/list-users

Method: GET

Authentication: Bearer Token

Request Headers

Request Parameters

Request Body

Example Request

Response Fields

Example Response

Example Error Response

Update User in Server Group

Path: /server-groups/update-user

Method: PATCH

Authentication: Bearer Token

Request Headers

Path: `/server-groups/list`

Method: `GET`

Authentication: `Bearer Token`

Path: `/server-groups/view`

Method: `GET`

Authentication: `Bearer Token`

Path: `/server-groups/create`

Method: `POST`

Authentication: `Bearer Token`

Path: `/server-groups/set-default`

Method: `POST`

Authentication: `Bearer Token`

Path: `/server-groups/update`

Method: `PATCH`

Authentication: `Bearer Token`

Path: `/server-groups/delete`

Method: `DELETE`

Authentication: `Bearer Token`

Path: `/server-groups/list-users`

Method: `GET`

Authentication: `Bearer Token`

Path: `/server-groups/update-user`

Method: `PATCH`

Authentication: `Bearer Token`

Path: `/server-groups/list-user-groups`

Method: `GET`

Authentication: `Bearer Token`

Path: `/server-groups/update-user-group`

Method: `PATCH`

Authentication: `Bearer Token`