Provision groups with SCIM

Through the /Groups endpoint, a provisioning system manages the groups of your organization and their members. Groups created through SCIM are regular groups: they appear under Groups in the admin console, and you give them access to applications there, like any other group.

All paths below are relative to your organization’s SCIM base URL. The protocol details common to users and groups are in the SCIM API reference.

How SCIM attributes map to BreezeAuth

SCIM attribute	In BreezeAuth
id	The group’s identifier in BreezeAuth.
displayName	Name. Required.
externalId	The group’s identifier in the provisioning system. Kept by BreezeAuth, not shown in the console. Unique in the organization.
members	The group’s direct members: users and other groups.

The group’s Identifier is generated by BreezeAuth from the name when the group is created, for example sales-team for “Sales Team”, with a number added if it is already taken (sales-team-2). Renaming the group later doesn’t change it. The group’s Description isn’t managed through SCIM: you can fill it in the admin console.

Members

Each member is identified by its SCIM id and its type:

"members": [
  { "value": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d", "type": "User" },
  { "value": "9a8b7c6d-5e4f-4321-9876-0fedcba98765", "type": "Group" }
]

Field	Description
value	The id of a user or of another group.
type	User or Group. Required: a member without a valid type is refused with 400 Bad Request.
display	Optional, and ignored by BreezeAuth.

A member of type Group makes a nested group: the users of the inner group become indirect members of the outer one, and get the applications assigned to it. A group can’t be a member of itself.

SCIM only ever shows and changes direct members, the ones added to the group itself. The indirect members that come from nested groups are not listed, which is also what the Show only direct associations option shows in the admin console.

Create a group

POST /Groups
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Sales Team",
  "externalId": "grp-0042",
  "members": [{ "value": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d", "type": "User" }]
}

BreezeAuth returns 201 Created with the new group, and its address in the Location header:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "9a8b7c6d-5e4f-4321-9876-0fedcba98765",
  "displayName": "Sales Team",
  "externalId": "grp-0042",
  "members": [{ "value": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d", "type": "User" }],
  "meta": {
    "resourceType": "Group",
    "created": "2026-10-13T14:35:12.000Z",
    "lastModified": "2026-10-13T14:35:12.000Z",
    "location": "https://api.breezeauth.com/organizations/0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d/scim/v2/Groups/9a8b7c6d-5e4f-4321-9876-0fedcba98765"
  }
}

members is optional: many provisioning systems create the group first and add the members afterwards.

Find and read groups

Request	Returns
GET /Groups/{id}	One group, with its direct members.
GET /Groups	All the groups of the organization, one page at a time, without members.
GET /Groups?filter=displayName eq "Sales Team"	The group with that name, if any.
GET /Groups?filter=externalId eq "grp-0042"	The group with that external ID, if any.

To get the members of a group, read the group itself. A group with more than 1,000 direct members can’t be read or updated through SCIM: the request fails with 400 Bad Request and scimType tooMany.

Update a group

Replace a group (PUT)

PUT /Groups/{id} replaces the group’s name, external ID and members with the body you send. The member list you send becomes the group’s complete list of direct members: members that are not in it are removed, and sending no members at all removes every member. If externalId is left out, it is cleared.

Change some attributes (PATCH)

PATCH /Groups/{id} is the usual way to rename a group and to add or remove members without sending the whole list:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [{ "value": "b4c0d2e3-8f5a-4b7c-9d6e-0f1a2b3c4d5e", "type": "User" }]
    },
    { "op": "remove", "path": "members[value eq \"a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d\"]" }
  ]
}

The supported operations are:

Operation	Path	Effect
add	members	Adds the members in value. Members already in the group are ignored.
replace	members	Replaces all direct members with the ones in value.
remove	members[value eq "{id}"]	Removes that one member.
remove	members	Removes all direct members, whatever value contains.
add or replace	displayName	Renames the group.
add or replace	externalId	Changes the external ID.
remove	externalId	Clears the external ID.

An add or replace operation can also leave out path and send an object as value, with displayName, externalId and members. In that form, add adds the members and replace replaces them.

Operations are applied in the order they are listed. If one fails, for example because a member doesn’t exist, the operations before it stay applied: read the group to see its current state before retrying.

Delete a group

DELETE /Groups/{id}

As in the admin console, a group can only be deleted when it has no members. Otherwise the request fails with 409 Conflict. Remove the members first, for example with a remove operation on members, then delete the group.

When the group is deleted, BreezeAuth returns 204 No Content. The group’s application assignments are removed with it. This can’t be undone.

Give provisioned groups access to applications

SCIM doesn’t assign applications. Once a provisioned group exists, assign its applications in the admin console, once. From then on, everyone the provisioning system adds to the group gets access automatically, and loses it when they are removed. See Application access.