API: Groups

API v6

Sections: List groups | Show a group | Create a group | Update a group | Add a user to a group | Delete a user from a group | Delete a group

List groups

Returns all the groups in Team Password Manager:

GET /groups.json

The response from these request is paginated and /count.json, /page/num.json and X-Page-Size can be used. See the section on pagination for more information. Example: GET /groups/page/2.json

If successful, the response code is 200 OK with the results of the call in the response body.

*Note: users with "Normal user" and "Project Manager" roles can also execute this request. Users with "Read only" role can't.

Example response body:

[
  {
        "id": 3,
        "name": "External users",
        "is_ldap": false,
        "num_users": 1,
        "created_by": {
            "id": 1
        },
        "created_on": "2024-12-16 14:36:06",
        "updated_by": {
            "id": 1
        },
        "updated_on": "2024-12-16 14:36:07"
    },
    {
        "id": 2,
        "name": "IT work",
        "is_ldap": false,
        "num_users": 3,
        "created_by": {
            "id": 1
        },
        "created_on": "2024-12-16 14:36:06",
        "updated_by": {
            "id": 1
        },
        "updated_on": "2024-12-16 14:36:07"
    },
    ...
]

Metadata only lists

The group list request can include the following header: X-Metadata-Only: true. When this header is used, the response will only include the metadata fields of the groups. For example:

[
    {
        "id": 3,
        "created_by": {
            "id": 1
        },
        "created_on": "2024-12-16 14:36:06",
        "updated_by": {
            "id": 1
        },
        "updated_on": "2024-12-16 14:36:07"
    },
    {
        "id": 2,
        "created_by": {
            "id": 1
        },
        "created_on": "2024-12-16 14:36:06",
        "updated_by": {
            "id": 1
        },
        "updated_on": "2024-12-16 14:36:07"
    },
    ...
]

Show a group

This method returns all the data of a group, identified by its internal id.

GET /groups/ID.json

If successful, the response code is 200 OK with the results of the call in the response body.

*Note: users with "Normal user" and "Project Manager" roles can also execute this request. Users with "Read only" role can't.

Example response body:

{
  "id": 24,
  "name": "IT managers",
  "is_ldap": true,
  "ldap_server_id": 8,
  "group_dn": "CN=IS Helpdesk,OU=Groups - Security,OU=Group Policy OU,DC=TPMAD,DC=local",
  "users": [
    {
      "id": 1,
      "username": "john",
      "email_address": "john@teampasswordmanager.com",
      "name": "John Boss",
      "role": "Admin"
    },
    {
      "id": 7,
      "username": "janine@teampasswordmanager.com",
      "email_address": "janine@teampasswordmanager.com",
      "name": "Janine Black",
      "role": "Normal user"
    },
    {
      "id": 8,
      "username": "tom@teampasswordmanager.com",
      "email_address": "tom@teampasswordmanager.com",
      "name": "Tom Landy",
      "role": "Normal user"
    }
  ],
  "created_on": "2014-06-05 16:35:12",
  "created_by": {
    "id": 1,
    "username": "john",
    "email_address": "john@teampasswordmanager.com",
    "name": "John Boss",
    "role": "Admin"
  },
  "updated_on": "2014-07-23 23:53:51",
  "updated_by": {
    "id": 1,
    "username": "john",
    "email_address": "john@teampasswordmanager.com",
    "name": "John Boss",
    "role": "Admin"
  }
}

Metadata only

The show a group request can include the following header: X-Metadata-Only: true. When this header is used, the response will only include the metadata fields of the group. For example:

{
    "id": 3,
    "created_by": {
        "id": 1
    },
    "created_on": "2024-12-16 14:36:06",
    "updated_by": {
        "id": 1
    },
    "updated_on": "2024-12-16 14:36:07"
}

Create a group

POST /groups.json

The request body must include the name for the group (which is the only field that can be set in a group):

{
  "name": "This is a new group"
}

If successful, the response code is 201 Created with the internal id of the group in the response body:

{
  "id": 15
}

Update a group

PUT /groups/ID.json

The request body must include the name for the group (which is the only field to be updated):

{
  "name": "This group is not new anymore"
}

If successful, the response code is 204 No content and the response body is empty.

Add a user to a group

PUT /groups/GROUP_ID/add_user/USER_ID.json

If successful, the response code is 204 No content and the response body is empty.

Delete a user from a group

PUT /groups/GROUP_ID/delete_user/USER_ID.json

If successful, the response code is 204 No content and the response body is empty.

Delete a group

DELETE /groups/ID.json

If successful, the response code is 204 No content and the response body is empty.