groups

get

Lists all groups

Authorizations

Responses

200

Happy response.

application/json

default

Error object.

application/json

get

/v1/groups

GET /v1/groups HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-10-24T16:06:07.052Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "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.

sso_namestring · min: 1 · max: 150Optional

Sets the SSO name of the new group. If not provided, the value of "name" will be used. When users sign in via SSO, this field is used to map SSO-provided groups onto HQ groups. Having a dedicated field helps in e.g. the Active Directory situation, where the groups in the SAML assertion are passed as UUIDs. E.g., one can have a group named "my-group" with display_name "My Group of Lovely People" and sso_name "f3f2e850-b5d4-11ef-ac7e-96584d5248b2".

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.

Responses

201

Happy response.

application/json

default

Error object.

application/json

post

/v1/groups

POST /v1/groups HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 158

{
  "name": "text",
  "display_name": "text",
  "sso_name": "text",
  "description": "text",
  "members": [
    "text"
  ],
  "roles": [
    "text"
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "name": "text",
  "display_name": "text",
  "sso_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-10-24T16:06:07.052Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "description": "text",
      "id": "text",
      "created_at": "2025-10-24T16:06:07.052Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-10-24T16:06:07.052Z",
      "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-10-24T16:06:07.052Z",
      "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

200

Happy response.

application/json

default

Error object.

application/json

get

/v1/groups/{name}

GET /v1/groups/{name} HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "display_name": "text",
  "sso_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-10-24T16:06:07.052Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "description": "text",
      "id": "text",
      "created_at": "2025-10-24T16:06:07.052Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-10-24T16:06:07.052Z",
      "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-10-24T16:06:07.052Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

delete

Deletes a group.

Authorizations

Path parameters

namestringRequired

Responses

204

Successful deletion.

No content

default

Error object.

application/json

delete

/v1/groups/{name}

DELETE /v1/groups/{name} HTTP/1.1
Host: 
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.

sso_namestring · min: 1 · max: 150Optional

Updates the SSO 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.

Responses

200

Happy response.

application/json

default

Error object.

application/json

patch

/v1/groups/{name}

PATCH /v1/groups/{name} HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 197

{
  "display_name": "text",
  "sso_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",
  "sso_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-10-24T16:06:07.052Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "description": "text",
      "id": "text",
      "created_at": "2025-10-24T16:06:07.052Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-10-24T16:06:07.052Z",
      "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-10-24T16:06:07.052Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

PreviousagentProxy Nextusers

Last updated 2 days ago

Was this helpful?