Home
ProductsDownload Community Edition

Groups

delete

Deletes a group.

Authorizations
Path parameters
namestringRequired
Responses
delete
DELETE /api/v1/groups/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content
patch

Updates a group.

Authorizations
Path parameters
namestringRequired
Body
display_namestring · min: 1 · max: 150Optional

Updates the display name of the group.

descriptionstring · max: 250Optional

Updates the Group description, if a value is provided.

rolesstring[]Optional

Sets the Roles that are bound to this Group to the Roles (specified by their names), if provided.

add_membersstring[]Optional

Adds the users/principals (specified by their names) to this group, if provided.

remove_membersstring[]Optional

Removes the users/principals (specified by their names) from this group, if provided. If members are specified in both add_members as well in here, removal wins.

set_membersstring[]Optional

Sets the members of this group to those users/principals (specified by their names) in an absolute fashion, if provided. Cannot be combined with the add_members or remove_members fields.

metadataobjectOptional

Patches metadata. It has the following semantics:

  • Absent keys are left untouched;
  • Null values are deleted;
  • Non-null values are replaced.
Responses
application/json
objectOptional

Contains Users and Service accounts, and the Roles assigned to it.

patch
PATCH /api/v1/groups/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 179

{
  "display_name": "text",
  "description": "text",
  "roles": [
    "text"
  ],
  "add_members": [
    "text"
  ],
  "remove_members": [
    "text"
  ],
  "set_members": [
    "text"
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-24T01:02:52.233Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-24T01:02:52.233Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-24T01:02:52.233Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-24T01:02:52.233Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
get

Gets a group by its name.

Authorizations
Path parameters
namestringRequired
Responses
application/json
objectOptional

Contains Users and Service accounts, and the Roles assigned to it.

get
GET /api/v1/groups/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-24T01:02:52.233Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-24T01:02:52.233Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-24T01:02:52.233Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-24T01:02:52.233Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
post

Creates a new Group.

Authorizations
Body
namestring · hq-resource-name · min: 1 · max: 63Required

Sets the unique name of the new group. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.

display_namestring · min: 1 · max: 150Optional

Sets the display name of the new group. If not provided, the value of "name" will be used.

descriptionstring · max: 250Optional

Sets the description of the new group.

membersstring[]Optional

Lists principal names (users, service accounts) to be member of this group.

rolesstring[]Optional

Sets the Roles that are bound to this Group by name.

metadataobjectOptional

Allows attaching custom string key/values to resources. The following maxima apply:

  • 50 keys/values;
  • 40 bytes key length;
  • 500 bytes value length.
Responses
application/json
objectOptional

Contains Users and Service accounts, and the Roles assigned to it.

post
POST /api/v1/groups HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "name": "text",
  "display_name": "text",
  "description": "text",
  "members": [
    "text"
  ],
  "roles": [
    "text"
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-24T01:02:52.233Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-24T01:02:52.233Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-24T01:02:52.233Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-24T01:02:52.233Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
get

Lists all groups

Authorizations
Responses
application/json
objectOptional

Contains a list of CompactGroups.

get
GET /api/v1/groups HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-24T01:02:52.233Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}
PreviousUsersNextRoles

Last updated

Was this helpful?