> For the complete documentation index, see [llms.txt](https://developer.collibra.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.collibra.com/api/references/protect/groups.md).
# Groups
Manage groups.
## List groups
> Lists all available groups.
```json
{"openapi":"3.0.3","info":{"title":"Collibra Protect API","version":"1.0.0"},"tags":[{"name":"Groups","description":"Manage groups."}],"servers":[{"url":"/rest/protect/v1"}],"security":[{"basicAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"Collibra REST API authentication using Basic Authentication."},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Collibra REST API authentication using JSON Web Token."}},"parameters":{"ProtectGroupName":{"name":"name","in":"query","description":"The name of the group.","required":false,"schema":{"type":"string"}},"ProtectGroupMapping":{"name":"mapping","in":"query","description":"The group mapping which can contain provider or identity.","required":false,"schema":{"type":"string"}},"ProtectGroupCreatedOn":{"name":"createdOn","in":"query","description":"The created date of the group.","required":false,"schema":{"type":"string","format":"date"}},"ProtectGroupLastModifiedOn":{"name":"lastModifiedOn","in":"query","description":"The last modified date of the group.","required":false,"schema":{"type":"string","format":"date"}},"ProtectGroupSortField":{"name":"sortField","in":"query","description":"A field to sort the groups.","required":false,"schema":{"$ref":"#/components/schemas/ProtectGroupSortFieldOptions"}},"ProtectGroupSortFieldOrder":{"name":"sortOrder","in":"query","description":"Sorting order to be applied on the sort field.","required":false,"schema":{"$ref":"#/components/schemas/ProtectGroupSortFieldOrder"}},"Limit":{"name":"limit","in":"query","description":"This is the maximum number of results that may be returned. Fewer may be returned than the value of limit.\n\nDo not depend on the number of results being fewer than the limit value\nto indicate that your query reached the end of the list of data, use the absence of after (see Cursors) instead.\nFor example, if you set limit to 10 and 9 results are returned, there may be more data available.\n\nIf not set, the default limit (limit = 25) will be used. The maximum value for this parameter is 500.\n","schema":{"type":"integer","default":25,"minimum":1,"maximum":500}},"After":{"name":"after","in":"query","description":"This is the cursor that points to the end of the page of data that has been returned.","schema":{"type":"string","nullable":true}}},"schemas":{"ProtectGroupSortFieldOptions":{"type":"string","description":"Sort field options available for groups. Possible values are: `NAME`, `CREATED_ON` or `LAST_MODIFIED_ON`."},"ProtectGroupSortFieldOrder":{"description":"Order on the sort field options available for groups. Possible values are: `ASC` or `DESC`.","type":"string"},"PagedGroups":{"description":"A page of groups.","type":"object","properties":{"cursors":{"$ref":"#/components/schemas/Cursors"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Group"}}},"required":["cursors","results"]},"Cursors":{"description":"A cursor refers to a random string of characters which marks a specific item in a list of data.\nThe cursor will always point to the item, however it will be invalidated if the item is deleted or removed.\nTherefore, your app shouldn't store cursors or assume that they will be valid in the future.\n","type":"object","properties":{"after":{"description":"This is the cursor that points to the end of the page of data that has been returned.","type":"string"}}},"Group":{"type":"object","properties":{"id":{"description":"The ID of the group.","type":"string","format":"uuid"},"createdBy":{"description":"Id of the Collibra user who created this group","type":"string","format":"uuid"},"createdOn":{"description":"Timestamp when this group is created","type":"integer","format":"int64"},"lastModifiedBy":{"description":"Id of the Collibra user who last updated this group","type":"string","format":"uuid"},"lastModifiedOn":{"description":"Timestamp when this group has last been updated","type":"integer","format":"int64"}},"allOf":[{"$ref":"#/components/schemas/EditableGroup"}],"required":["id","createdBy","createdOn","lastModifiedBy","lastModifiedOn"]},"EditableGroup":{"type":"object","properties":{"name":{"description":"The name of the group.","type":"string"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/GroupMapping"}}},"required":["name","mappings"]},"GroupMapping":{"description":"This dictionary describes to which Snowflake, GoogleBigQuery or AWSLakeFormation roles this group maps to.","type":"object","properties":{"provider":{"$ref":"#/components/schemas/Provider"},"identity":{"description":"An existing Snowflake, GoogleBigQuery or AWSLakeFormation role.","type":"string"}},"required":["provider","identity"]},"Provider":{"type":"string","description":"Value must be \"Snowflake\", \"GoogleBigQuery, or \"AWSLakeFormation\""},"StandardErrorResponse":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP response code"},"titleMessage":{"type":"string","description":"The title of the error message."},"helpMessage":{"type":"string","description":"A message containing actions you can take regarding the error."},"userMessage":{"type":"string","description":"A user friendly error message."},"errorCode":{"type":"string","description":"An error code identifier."}},"required":["statusCode","userMessage"]}},"responses":{"InvalidRequest400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest401":{"description":"The client is not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest403":{"description":"The user lacks permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest500":{"description":"An unexpected error has occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/groups":{"get":{"tags":["Groups"],"summary":"List groups","description":"Lists all available groups.","operationId":"listGroups","parameters":[{"$ref":"#/components/parameters/ProtectGroupName"},{"$ref":"#/components/parameters/ProtectGroupMapping"},{"$ref":"#/components/parameters/ProtectGroupCreatedOn"},{"$ref":"#/components/parameters/ProtectGroupLastModifiedOn"},{"$ref":"#/components/parameters/ProtectGroupSortField"},{"$ref":"#/components/parameters/ProtectGroupSortFieldOrder"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/After"}],"responses":{"200":{"description":"The list of groups.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PagedGroups"}}}},"400":{"$ref":"#/components/responses/InvalidRequest400"},"401":{"$ref":"#/components/responses/InvalidRequest401"},"403":{"$ref":"#/components/responses/InvalidRequest403"},"500":{"$ref":"#/components/responses/InvalidRequest500"}}}}}}
```
## Add a new group
> Adds a new group.
```json
{"openapi":"3.0.3","info":{"title":"Collibra Protect API","version":"1.0.0"},"tags":[{"name":"Groups","description":"Manage groups."}],"servers":[{"url":"/rest/protect/v1"}],"security":[{"basicAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"Collibra REST API authentication using Basic Authentication."},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Collibra REST API authentication using JSON Web Token."}},"schemas":{"AddGroupRequest":{"type":"object","allOf":[{"$ref":"#/components/schemas/EditableGroup"}]},"EditableGroup":{"type":"object","properties":{"name":{"description":"The name of the group.","type":"string"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/GroupMapping"}}},"required":["name","mappings"]},"GroupMapping":{"description":"This dictionary describes to which Snowflake, GoogleBigQuery or AWSLakeFormation roles this group maps to.","type":"object","properties":{"provider":{"$ref":"#/components/schemas/Provider"},"identity":{"description":"An existing Snowflake, GoogleBigQuery or AWSLakeFormation role.","type":"string"}},"required":["provider","identity"]},"Provider":{"type":"string","description":"Value must be \"Snowflake\", \"GoogleBigQuery, or \"AWSLakeFormation\""},"Group":{"type":"object","properties":{"id":{"description":"The ID of the group.","type":"string","format":"uuid"},"createdBy":{"description":"Id of the Collibra user who created this group","type":"string","format":"uuid"},"createdOn":{"description":"Timestamp when this group is created","type":"integer","format":"int64"},"lastModifiedBy":{"description":"Id of the Collibra user who last updated this group","type":"string","format":"uuid"},"lastModifiedOn":{"description":"Timestamp when this group has last been updated","type":"integer","format":"int64"}},"allOf":[{"$ref":"#/components/schemas/EditableGroup"}],"required":["id","createdBy","createdOn","lastModifiedBy","lastModifiedOn"]},"StandardErrorResponse":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP response code"},"titleMessage":{"type":"string","description":"The title of the error message."},"helpMessage":{"type":"string","description":"A message containing actions you can take regarding the error."},"userMessage":{"type":"string","description":"A user friendly error message."},"errorCode":{"type":"string","description":"An error code identifier."}},"required":["statusCode","userMessage"]}},"responses":{"InvalidRequest400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest401":{"description":"The client is not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest403":{"description":"The user lacks permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest409":{"description":"Conflicts found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest500":{"description":"An unexpected error has occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/groups":{"post":{"tags":["Groups"],"summary":"Add a new group","description":"Adds a new group.","operationId":"addGroup","requestBody":{"description":"The group to add.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddGroupRequest"}}}},"responses":{"201":{"description":"The group has been added.","headers":{"Location":{"description":"The URL of the added group.","schema":{"type":"string","format":"uri"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}},"400":{"$ref":"#/components/responses/InvalidRequest400"},"401":{"$ref":"#/components/responses/InvalidRequest401"},"403":{"$ref":"#/components/responses/InvalidRequest403"},"409":{"$ref":"#/components/responses/InvalidRequest409"},"500":{"$ref":"#/components/responses/InvalidRequest500"}}}}}}
```
## Retrieve a group
> Returns information about the group with the specified ID.
```json
{"openapi":"3.0.3","info":{"title":"Collibra Protect API","version":"1.0.0"},"tags":[{"name":"Groups","description":"Manage groups."}],"servers":[{"url":"/rest/protect/v1"}],"security":[{"basicAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"Collibra REST API authentication using Basic Authentication."},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Collibra REST API authentication using JSON Web Token."}},"schemas":{"Group":{"type":"object","properties":{"id":{"description":"The ID of the group.","type":"string","format":"uuid"},"createdBy":{"description":"Id of the Collibra user who created this group","type":"string","format":"uuid"},"createdOn":{"description":"Timestamp when this group is created","type":"integer","format":"int64"},"lastModifiedBy":{"description":"Id of the Collibra user who last updated this group","type":"string","format":"uuid"},"lastModifiedOn":{"description":"Timestamp when this group has last been updated","type":"integer","format":"int64"}},"allOf":[{"$ref":"#/components/schemas/EditableGroup"}],"required":["id","createdBy","createdOn","lastModifiedBy","lastModifiedOn"]},"EditableGroup":{"type":"object","properties":{"name":{"description":"The name of the group.","type":"string"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/GroupMapping"}}},"required":["name","mappings"]},"GroupMapping":{"description":"This dictionary describes to which Snowflake, GoogleBigQuery or AWSLakeFormation roles this group maps to.","type":"object","properties":{"provider":{"$ref":"#/components/schemas/Provider"},"identity":{"description":"An existing Snowflake, GoogleBigQuery or AWSLakeFormation role.","type":"string"}},"required":["provider","identity"]},"Provider":{"type":"string","description":"Value must be \"Snowflake\", \"GoogleBigQuery, or \"AWSLakeFormation\""},"StandardErrorResponse":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP response code"},"titleMessage":{"type":"string","description":"The title of the error message."},"helpMessage":{"type":"string","description":"A message containing actions you can take regarding the error."},"userMessage":{"type":"string","description":"A user friendly error message."},"errorCode":{"type":"string","description":"An error code identifier."}},"required":["statusCode","userMessage"]}},"responses":{"InvalidRequest400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest401":{"description":"The client is not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest403":{"description":"The user lacks permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest500":{"description":"An unexpected error has occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/groups/{id}":{"get":{"tags":["Groups"],"summary":"Retrieve a group","description":"Returns information about the group with the specified ID.","operationId":"getGroup","parameters":[{"in":"path","description":"The universally unique identifier (UUID) of the group.","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The group with the specified ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}},"400":{"$ref":"#/components/responses/InvalidRequest400"},"401":{"$ref":"#/components/responses/InvalidRequest401"},"403":{"$ref":"#/components/responses/InvalidRequest403"},"404":{"$ref":"#/components/responses/InvalidRequest404"},"500":{"$ref":"#/components/responses/InvalidRequest500"}}}}}}
```
## Delete a group
> Deletes the group with the specified ID.
```json
{"openapi":"3.0.3","info":{"title":"Collibra Protect API","version":"1.0.0"},"tags":[{"name":"Groups","description":"Manage groups."}],"servers":[{"url":"/rest/protect/v1"}],"security":[{"basicAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"Collibra REST API authentication using Basic Authentication."},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Collibra REST API authentication using JSON Web Token."}},"responses":{"InvalidRequest400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest401":{"description":"The client is not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest403":{"description":"The user lacks permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest500":{"description":"An unexpected error has occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}},"schemas":{"StandardErrorResponse":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP response code"},"titleMessage":{"type":"string","description":"The title of the error message."},"helpMessage":{"type":"string","description":"A message containing actions you can take regarding the error."},"userMessage":{"type":"string","description":"A user friendly error message."},"errorCode":{"type":"string","description":"An error code identifier."}},"required":["statusCode","userMessage"]}}},"paths":{"/groups/{id}":{"delete":{"tags":["Groups"],"summary":"Delete a group","description":"Deletes the group with the specified ID.","operationId":"deleteGroup","parameters":[{"in":"path","description":"The universally unique identifier (UUID) of the group.","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"The group has been deleted."},"400":{"$ref":"#/components/responses/InvalidRequest400"},"401":{"$ref":"#/components/responses/InvalidRequest401"},"403":{"$ref":"#/components/responses/InvalidRequest403"},"404":{"$ref":"#/components/responses/InvalidRequest404"},"500":{"$ref":"#/components/responses/InvalidRequest500"}}}}}}
```
## Update a group
> Updates the group with the specified ID.
```json
{"openapi":"3.0.3","info":{"title":"Collibra Protect API","version":"1.0.0"},"tags":[{"name":"Groups","description":"Manage groups."}],"servers":[{"url":"/rest/protect/v1"}],"security":[{"basicAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"Collibra REST API authentication using Basic Authentication."},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Collibra REST API authentication using JSON Web Token."}},"schemas":{"ChangeGroupRequest":{"type":"object","properties":{"name":{"description":"The name of the group.","type":"string"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/GroupMapping"}}}},"GroupMapping":{"description":"This dictionary describes to which Snowflake, GoogleBigQuery or AWSLakeFormation roles this group maps to.","type":"object","properties":{"provider":{"$ref":"#/components/schemas/Provider"},"identity":{"description":"An existing Snowflake, GoogleBigQuery or AWSLakeFormation role.","type":"string"}},"required":["provider","identity"]},"Provider":{"type":"string","description":"Value must be \"Snowflake\", \"GoogleBigQuery, or \"AWSLakeFormation\""},"Group":{"type":"object","properties":{"id":{"description":"The ID of the group.","type":"string","format":"uuid"},"createdBy":{"description":"Id of the Collibra user who created this group","type":"string","format":"uuid"},"createdOn":{"description":"Timestamp when this group is created","type":"integer","format":"int64"},"lastModifiedBy":{"description":"Id of the Collibra user who last updated this group","type":"string","format":"uuid"},"lastModifiedOn":{"description":"Timestamp when this group has last been updated","type":"integer","format":"int64"}},"allOf":[{"$ref":"#/components/schemas/EditableGroup"}],"required":["id","createdBy","createdOn","lastModifiedBy","lastModifiedOn"]},"EditableGroup":{"type":"object","properties":{"name":{"description":"The name of the group.","type":"string"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/GroupMapping"}}},"required":["name","mappings"]},"StandardErrorResponse":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP response code"},"titleMessage":{"type":"string","description":"The title of the error message."},"helpMessage":{"type":"string","description":"A message containing actions you can take regarding the error."},"userMessage":{"type":"string","description":"A user friendly error message."},"errorCode":{"type":"string","description":"An error code identifier."}},"required":["statusCode","userMessage"]}},"responses":{"InvalidRequest400":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest401":{"description":"The client is not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest403":{"description":"The user lacks permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest409":{"description":"Conflicts found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InvalidRequest500":{"description":"An unexpected error has occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/groups/{id}":{"patch":{"tags":["Groups"],"summary":"Update a group","description":"Updates the group with the specified ID.","operationId":"patchGroup","parameters":[{"in":"path","description":"The universally unique identifier (UUID) of the group.","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"The changes that need to be applied to the group.","required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeGroupRequest"}}}},"responses":{"200":{"description":"Group has been updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}},"400":{"$ref":"#/components/responses/InvalidRequest400"},"401":{"$ref":"#/components/responses/InvalidRequest401"},"403":{"$ref":"#/components/responses/InvalidRequest403"},"404":{"$ref":"#/components/responses/InvalidRequest404"},"409":{"$ref":"#/components/responses/InvalidRequest409"},"500":{"$ref":"#/components/responses/InvalidRequest500"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.collibra.com/api/references/protect/groups.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.