User Groups

The User Groups resource provides access to all methods relating to User Groups in Keystash.

List User Groups

Path: /user-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/user-groups/list' \
--header 'Authorization: Bearer <token>'

Example Response

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

[
  {
    "id": "x0Uf09z3TYjoNVFv",
    "name": "Development Team",
    "description": "Developers who need access to development servers",
    "user_count": 5,
    "created": "2023-11-14 16:53:55",
    "created_by": "Max Smith",
    "created_user_id": "DmcEgixUXpWVv7tk",
    "modified": "2023-11-15 09:22:10",
    "modified_by": "Anne Teak",
    "modified_user_id": "p8CduXmyw6n9dzdd"
  },
  {
    "id": "p8CduXmyw6n9dzdd",
    "name": "System Administrators",
    "description": "Administrators with full system access",
    "user_count": 3,
    "created": "2023-10-20 14:30:12",
    "created_by": "Perry Scope",
    "created_user_id": "BD720EP87kNORRcH",
    "modified": "2023-11-10 11:45:33",
    "modified_by": "Max Smith",
    "modified_user_id": "DmcEgixUXpWVv7tk"
  }
]

Example Error Response

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

{
  "error": {
    "code": "NotFound",
    "message": "The User Groups were not found.",
    "details": []
  }
}

View User Group

Path: /user-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 user group to view

Request Body

None.

Example Request

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

Example Response

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

{
    "id": "x0Uf09z3TYjoNVFv",
    "name": "Development Team",
    "description": "Developers who need access to development servers",
    "user_count": 5,
    "created": "2023-11-14 16:53:55",
    "created_by": "Max Smith",
    "created_user_id": "DmcEgixUXpWVv7tk",
    "modified": "2023-11-15 09:22:10",
    "modified_by": "Anne Teak",
    "modified_user_id": "p8CduXmyw6n9dzdd"
}

Example Error Response

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

{
  "error": {
    "code": "NotFound",
    "message": "There was a problem while trying to retrieve the User Group ID specified. Could not find a User Group by that ID.",
    "details": []
  }
}

List Users in Group

Path: /user-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 user group whose users are to be listed

Request Body

None.

Example Request

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

Example Response

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

[
  {
    "user_id": "DmcEgixUXpWVv7tk",
    "firstname": "Max",
    "lastname": "Smith",
    "email": "max.smith@example.org",
    "server_username": "maxsmith"
  },
  {
    "user_id": "p8CduXmyw6n9dzdd",
    "firstname": "Anne",
    "lastname": "Teak",
    "email": "anne.teak@example.org",
    "server_username": "anneteak"
  },
  {
    "user_id": "BD720EP87kNORRcH",
    "firstname": "Perry",
    "lastname": "Scope",
    "email": "perry.scope@example.org", 
    "server_username": "perryscope"
  }
]

Example Error Response

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

{
  "error": {
    "code": "NotFound",
    "message": "There was a problem while trying to retrieve the User Group ID specified. Could not find a User Group by that ID.",
    "details": []
  }
}

Create User Group

Path: /user-groups/create

Method: POST

Authentication: Bearer Token

Request Headers

Key	Value	Required
Content-Type	application/json	required
Accept-Encoding	gzip	optional

Request Parameters

None.

Request Body Parameters

Key	Data Type	Required	Notes
name	string	required	The name of the user group
description	string	optional	A description of the user group and its purpose

Example Request Body

{
  "name": "Production Team",
  "description": "Team members who require access to production servers"
}

Example Request

curl --location --request POST 'https://app.keystash.io/api/v1/user-groups/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
    "name": "Production Team",
    "description": "Team members who require access to production servers"
}'

Example Response

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

{
  "result": "User Group 'Production Team' was successfully created.",
  "id": "x0Uf09z3TYjoNVFv"
}

Example Error Response

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

{
  "error": {
    "code": "BadArgument",
    "message": "There were data validation issues with the arguments you provided. Please check your arguments and resubmit.",
    "details": [
      {
        "message": "Group name is required and cannot be empty.",
        "field": "name"
      }
    ]
  }
}

Update User Group

Path: /user-groups/update

Method: PATCH

Authentication: Bearer Token

Request Headers

Key	Value	Required
Content-Type	application/json	required
Accept-Encoding	gzip	optional

Request Parameters

None.

Request Body Parameters

Key	Data Type	Required	Notes
id	string	required	The ID of the user group to update
name	string	optional	The new name of the user group
description	string	optional	The new description of the user group

Example Request Body

{
  "id": "x0Uf09z3TYjoNVFv",
  "name": "Senior Developers",
  "description": "Senior developers who need access to production servers"
}

Example Request

curl --location --request PATCH 'https://app.keystash.io/api/v1/user-groups/update' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
    "id": "x0Uf09z3TYjoNVFv",
    "name": "Senior Developers",
    "description": "Senior developers who need access to production servers"
}'

Example Response

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

{
  "result": "User Group 'Senior Developers' was successfully updated."
}

Example Error Response

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

{
  "error": {
    "code": "BadArgument",
    "message": "There were data validation issues with the arguments you provided. Please check your arguments and resubmit.",
    "details": [
      {
        "message": "Group name is required and cannot be empty.",
        "field": "name"
      }
    ]
  }
}

Update User in Group

Path: /user-groups/update-user

Method: PATCH

Authentication: Bearer Token

Request Headers

Key	Value	Required
Content-Type	application/json	required
Accept-Encoding	gzip	optional

Request Parameters

None.

Request Body Parameters

Key	Data Type	Required	Notes
id	string	required	The ID of the user group to update membership for
users_to_add	array	optional	Array of user IDs to add to the group
users_to_remove	array	optional	Array of user IDs to remove from the group

Note: At least one of users_to_add or users_to_remove must contain values.

Example Request Body

{
  "id": "x0Uf09z3TYjoNVFv",
  "users_to_add": ["p8CduXmyw6n9dzdd", "BD720EP87kNORRcH"],
  "users_to_remove": ["DmcEgixUXpWVv7tk"]
}

Example Request

curl --location --request PATCH 'https://app.keystash.io/api/v1/user-groups/update-user' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
    "id": "x0Uf09z3TYjoNVFv",
    "users_to_add": ["p8CduXmyw6n9dzdd", "BD720EP87kNORRcH"],
    "users_to_remove": ["DmcEgixUXpWVv7tk"]
}'

Example Response

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

{
  "result": "User Group 'Development Team' membership was successfully updated."
}

Example Error Response

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

{
  "error": {
    "code": "BadArgument",
    "message": "At least one of users_to_add or users_to_remove must contain values.",
    "details": []
  }
}

Delete User Group

Path: /user-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 user group to delete

Request Body

None.

Example Request

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

Example Response

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

{
  "result": "User Group with ID 'x0Uf09z3TYjoNVFv' was successfully deleted."
}

Example Error Response

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

{
  "error": {
    "code": "NotFound",
    "message": "User Group not found or you do not have permission to access it.",
    "details": []
  }
}