Groups
Groups bundle roles and resource grants so end-user access can be managed collectively. End users receive a group's access through membership, added manually or synced from an identity provider's group claims.
Group schema
Returns all active groups in the account. Requires account owner or administrator access.
List of groups.
A named bundle of roles and resource grants for end-user access management. End users receive the group's access through membership, whether added manually or synced from an identity provider.
Unique identifier for the group.
68a1b2c3d4e5f6a7b8c9d0e1Account owner's user id.
5f8d43a1b9e5a80011a35f2cGroup name, unique within the account (case-insensitive).
FinanceFree-text description of the group's purpose.
Finance department end usersRoles pinned to this group. Members receive the roles' grants through the group.
When true, at least one end user's membership in this group is synced from an identity provider's group claims. Maintained by the server — IdP-synced memberships cannot be removed through the group members API.
Timestamp when the group was created.
2026-07-01T09:15:32ZTimestamp when the group was last updated.
2026-08-15T14:30:15ZNo groups exist in the account.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Forbidden. The authenticated caller does not have permission to perform this operation.
GET /v1/groups HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"_id": "68a1b2c3d4e5f6a7b8c9d0e1",
"_userId": "5f8d43a1b9e5a80011a35f2c",
"name": "Finance",
"description": "Finance department end users",
"intendedFor": [
"end-user"
],
"_roleIds": [
"68c1d2e3f4a5b6c7d8e9f0a1"
],
"resourceGrants": [],
"hasIdpSyncedMembers": false,
"createdAt": "2026-07-01T09:15:32Z",
"lastModified": "2026-08-15T14:30:15Z"
}
]Creates a group for end-user access management. Group names must be unique within the account (case-insensitive), and any _roleIds or resourceGrants._resourceId values must reference resources owned by the same account. Requires account owner or administrator access.
Writable fields for creating or replacing a group.
Group name, unique within the account (case-insensitive).
FinanceFree-text description of the group's purpose.
Finance department end usersRoles to pin to this group. Must reference roles owned by the same account.
Group created.
A named bundle of roles and resource grants for end-user access management. End users receive the group's access through membership, whether added manually or synced from an identity provider.
Unique identifier for the group.
68a1b2c3d4e5f6a7b8c9d0e1Account owner's user id.
5f8d43a1b9e5a80011a35f2cGroup name, unique within the account (case-insensitive).
FinanceFree-text description of the group's purpose.
Finance department end usersRoles pinned to this group. Members receive the roles' grants through the group.
When true, at least one end user's membership in this group is synced from an identity provider's group claims. Maintained by the server — IdP-synced memberships cannot be removed through the group members API.
Timestamp when the group was created.
2026-07-01T09:15:32ZTimestamp when the group was last updated.
2026-08-15T14:30:15ZBad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Forbidden. The authenticated caller does not have permission to perform this operation.
A group with this name already exists in the account.
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
POST /v1/groups HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18
{
"name": "Finance"
}{
"_id": "68a1b2c3d4e5f6a7b8c9d0e1",
"_userId": "5f8d43a1b9e5a80011a35f2c",
"name": "Finance",
"description": "Finance department end users",
"intendedFor": [
"end-user"
],
"_roleIds": [
"68c1d2e3f4a5b6c7d8e9f0a1"
],
"resourceGrants": [],
"hasIdpSyncedMembers": false,
"createdAt": "2026-07-01T09:15:32Z",
"lastModified": "2026-07-01T09:15:32Z"
}Retrieves a single group by ID.
Group ID.
Group details.
A named bundle of roles and resource grants for end-user access management. End users receive the group's access through membership, whether added manually or synced from an identity provider.
Unique identifier for the group.
68a1b2c3d4e5f6a7b8c9d0e1Account owner's user id.
5f8d43a1b9e5a80011a35f2cGroup name, unique within the account (case-insensitive).
FinanceFree-text description of the group's purpose.
Finance department end usersRoles pinned to this group. Members receive the roles' grants through the group.
When true, at least one end user's membership in this group is synced from an identity provider's group claims. Maintained by the server — IdP-synced memberships cannot be removed through the group members API.
Timestamp when the group was created.
2026-07-01T09:15:32ZTimestamp when the group was last updated.
2026-08-15T14:30:15ZBad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Forbidden. The authenticated caller does not have permission to perform this operation.
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/groups/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"_id": "68a1b2c3d4e5f6a7b8c9d0e1",
"_userId": "5f8d43a1b9e5a80011a35f2c",
"name": "Finance",
"description": "Finance department end users",
"intendedFor": [
"end-user"
],
"_roleIds": [
"text"
],
"resourceGrants": [
{
"resourceType": "mcpServer",
"_resourceId": "6a1b2c3d4e5f6a7b8c9d0e1f",
"capabilities": [
"tool:all"
]
}
],
"hasIdpSyncedMembers": true,
"createdAt": "2026-07-01T09:15:32Z",
"lastModified": "2026-08-15T14:30:15Z"
}Replaces the group's writable fields. Prefer resending the complete object — omitted fields are not preserved. Requires account owner or administrator access.
Group ID.
Writable fields for creating or replacing a group.
Group name, unique within the account (case-insensitive).
FinanceFree-text description of the group's purpose.
Finance department end usersRoles to pin to this group. Must reference roles owned by the same account.
Updated group.
A named bundle of roles and resource grants for end-user access management. End users receive the group's access through membership, whether added manually or synced from an identity provider.
Unique identifier for the group.
68a1b2c3d4e5f6a7b8c9d0e1Account owner's user id.
5f8d43a1b9e5a80011a35f2cGroup name, unique within the account (case-insensitive).
FinanceFree-text description of the group's purpose.
Finance department end usersRoles pinned to this group. Members receive the roles' grants through the group.
When true, at least one end user's membership in this group is synced from an identity provider's group claims. Maintained by the server — IdP-synced memberships cannot be removed through the group members API.
Timestamp when the group was created.
2026-07-01T09:15:32ZTimestamp when the group was last updated.
2026-08-15T14:30:15ZBad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Forbidden. The authenticated caller does not have permission to perform this operation.
Not found. The requested resource does not exist or is not visible to the caller.
A group with this name already exists in the account.
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
PUT /v1/groups/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 23
{
"name": "Finance EMEA"
}{
"_id": "68a1b2c3d4e5f6a7b8c9d0e1",
"_userId": "5f8d43a1b9e5a80011a35f2c",
"name": "Finance",
"description": "Finance department end users",
"intendedFor": [
"end-user"
],
"_roleIds": [
"text"
],
"resourceGrants": [
{
"resourceType": "mcpServer",
"_resourceId": "6a1b2c3d4e5f6a7b8c9d0e1f",
"capabilities": [
"tool:all"
]
}
],
"hasIdpSyncedMembers": true,
"createdAt": "2026-07-01T09:15:32Z",
"lastModified": "2026-08-15T14:30:15Z"
}Soft-deletes the group and removes the corresponding membership entry from every end user in the account. Requires account owner or administrator access.
Group ID.
Group deleted.
No content
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Forbidden. The authenticated caller does not have permission to perform this operation.
Not found. The requested resource does not exist or is not visible to the caller.
DELETE /v1/groups/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Bulk-adds up to 100 end users to the group as manual memberships. The operation is idempotent for end users already in the group. Requires account owner or administrator access.
Group ID.
End users to add to or remove from the group.
End-user access-record ids to add or remove.
Members added.
Outcome of a bulk membership change.
Number of end-user records updated. Members already in (or absent from) the group are not counted.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Forbidden. The authenticated caller does not have permission to perform this operation.
Not found. The requested resource does not exist or is not visible to the caller.
POST /v1/groups/{_groupId}/members HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 43
{
"_ashareIds": [
"68b1c2d3e4f5a6b7c8d9e0f1"
]
}{
"updated": 1
}Bulk-removes manual memberships from the group. Only manual memberships can be removed this way — attempting to remove an IdP-synced membership returns 409; change the IdP group mapping instead. Uses POST rather than DELETE so the request body survives proxies and CDNs. Requires account owner or administrator access.
Group ID.
End users to add to or remove from the group.
End-user access-record ids to add or remove.
Members removed.
Outcome of a bulk membership change.
Number of end-user records updated. Members already in (or absent from) the group are not counted.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Forbidden. The authenticated caller does not have permission to perform this operation.
Not found. The requested resource does not exist or is not visible to the caller.
One or more of the memberships is IdP-synced and cannot be removed
manually. Error code: conflict.
POST /v1/groups/{_groupId}/members/remove HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 43
{
"_ashareIds": [
"68b1c2d3e4f5a6b7c8d9e0f1"
]
}{
"updated": 1
}Last updated
Was this helpful?