Groups

Lists all groups

GEThttps://api.example.com/api/v1/groups

Response

200default

Happy response.

Body

application/json

items*array of CompactGroup (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/groups', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200default

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:03:47.170Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ]
}

Creates a new Group.

POSThttps://api.example.com/api/v1/groups

Body

application/json

name*string (hq-resource-name)

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

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

descriptionstring

Sets the description of the new group.

membersarray of string

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

rolesarray of string

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

metadataMetadata (object)

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

• 50 keys/values;
• 40 bytes key length;
• 500 bytes value length.

Response

201default

Happy response.

Body

application/json

name*string

Holds the name of the Group. Must be unique.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

roles*array of CompactRole (object)

users*array of CompactUser (object)

service_accounts*array of CompactServiceAccount (object)

metadataMetadata (object)

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

• 50 keys/values;
• 40 bytes key length;
• 500 bytes value length.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/groups', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text"
    }),
});
const data = await response.json();

Response

201default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-01-17T06:03:47.170Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:03:47.170Z",
      "policy_length": 0
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:03:47.170Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": false
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:03:47.170Z",
      "is_admin": false
    }
  ]
}

Gets a group by its name.

GEThttps://api.example.com/api/v1/groups/{name}

Path parameters

name*string

Response

200default

Happy response.

Body

application/json

name*string

Holds the name of the Group. Must be unique.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

roles*array of CompactRole (object)

users*array of CompactUser (object)

service_accounts*array of CompactServiceAccount (object)

metadataMetadata (object)

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

• 50 keys/values;
• 40 bytes key length;
• 500 bytes value length.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/groups/{name}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-01-17T06:03:47.170Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:03:47.170Z",
      "policy_length": 0
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:03:47.170Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": false
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:03:47.170Z",
      "is_admin": false
    }
  ]
}

Updates a group.

PATCHhttps://api.example.com/api/v1/groups/{name}

Path parameters

name*string

Body

application/json

display_namestring

Updates the display name of the group.

descriptionstring

Updates the Group description, if a value is provided.

rolesarray of string

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

add_membersarray of string

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

remove_membersarray of string

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_membersarray of string

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.

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

• Absent keys are left untouched;
• Null values are deleted;
• Non-null values are replaced.

Response

200default

Happy response.

Body

application/json

name*string

Holds the name of the Group. Must be unique.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

roles*array of CompactRole (object)

users*array of CompactUser (object)

service_accounts*array of CompactServiceAccount (object)

metadataMetadata (object)

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

• 50 keys/values;
• 40 bytes key length;
• 500 bytes value length.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/groups/{name}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-01-17T06:03:47.170Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:03:47.170Z",
      "policy_length": 0
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:03:47.170Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": false
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:03:47.170Z",
      "is_admin": false
    }
  ]
}

Deletes a group.

DELETEhttps://api.example.com/api/v1/groups/{name}

Path parameters

name*string

Response

204default

Successful deletion.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/groups/{name}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

default

{
  "type": "not_found",
  "title": "text",
  "status": 0,
  "invalid_fields": [
    {
      "name": "text",
      "error": "reference_not_found",
      "title": "text"
    }
  ],
  "sso_url": "text",
  "request_id": "text"
}