Provision users with SCIM

Through the /Users endpoint, a provisioning system manages the people of your organization: the users you see under Users › Human Users in the admin console. This page explains what each SCIM operation does in BreezeAuth. The protocol details common to users and groups, such as authentication, filtering, pagination and errors, are in the SCIM API reference.

All paths below are relative to your organization’s SCIM base URL.

What a SCIM user is

Each SCIM user is one user of your organization. Its id is the user’s identifier in BreezeAuth, the same value the BreezeAuth API calls membershipsUuid and that webhook events carry. Use it to read, update or delete the user, and to add them to groups.

Service users are not people, so they are never returned by /Users and can’t be changed through SCIM.

How SCIM attributes map to BreezeAuth

SCIM attribute	In BreezeAuth
userName	Email, the address the person signs in with. Required, and unique in the organization.
name.givenName	First name
name.familyName	Last name
displayName	Used to fill in the first and last name when name is missing. Returned as the full name.
active	Status: true for Active, false for Inactive. See Statuses.
externalId	The person’s identifier in the provisioning system. Kept by BreezeAuth, not shown in the console. Unique in the organization.
title	Job title
emails	The address that differs from userName, if any, is kept as a secondary e-mail address.
phoneNumbers with type work	Work phone
phoneNumbers with type mobile	Phone
addresses	The work address, or else the first one with data: streetAddress, locality (city), region (state) and postalCode.
photos	The person’s profile picture, from the first URL.
employeeNumber (Enterprise extension)	Employee ID
costCenter (Enterprise extension)	Cost center
organization (Enterprise extension)	Organizational unit
department (Enterprise extension)	Department
manager.value (Enterprise extension)	The person’s manager, as the SCIM id of another user.

The Enterprise extension attributes go inside the urn:ietf:params:scim:schemas:extension:enterprise:2.0:User object. Other attributes, such as password, roles, groups or locale, are ignored: a user’s groups are managed through /Groups, and roles only in the admin console.

Create a user

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

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "[email protected]",
  "externalId": "00u1a2b3c4",
  "name": { "givenName": "Ana", "familyName": "Souza" },
  "title": "Account Manager",
  "phoneNumbers": [{ "value": "+55 11 99999-9999", "type": "mobile" }],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "4021",
    "department": "Sales"
  }
}

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

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "id": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d",
  "userName": "[email protected]",
  "externalId": "00u1a2b3c4",
  "name": { "givenName": "Ana", "familyName": "Souza", "formatted": "Ana Souza" },
  "displayName": "Ana Souza",
  "active": true,
  "title": "Account Manager",
  "emails": [{ "value": "[email protected]", "type": "work", "primary": true }],
  "phoneNumbers": [{ "value": "+55 11 99999-9999", "type": "mobile" }],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "4021",
    "department": "Sales"
  },
  "meta": {
    "resourceType": "User",
    "created": "2026-10-13T14:32:05.000Z",
    "lastModified": "2026-10-13T14:32:05.000Z",
    "location": "https://api.breezeauth.com/organizations/0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d/scim/v2/Users/a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d"
  }
}

userName is required. If name is missing, BreezeAuth splits displayName into a first and a last name, and as a last resort uses the part of the e-mail before the @.

What happens next depends on the e-mail address, exactly as when an administrator adds a user:

E-mail address	Result
On one of your verified domains	A managed user, Active right away. The person receives a welcome e-mail.
On any other domain	A guest, Pending until they accept the invitation they receive by e-mail. Until then, SCIM returns them with active: false. See Invitations.

If active is false in the request, the user is created and then immediately deactivated.

Find and read users

Request	Returns
GET /Users/{id}	One user.
GET /Users	All the users of the organization, one page at a time.
GET /Users?filter=userName eq "[email protected]"	The user with that e-mail address, if any.
GET /Users?filter=externalId eq "00u1a2b3c4"	The user with that external ID, if any.

Provisioning systems usually search with one of these filters before creating a user, to avoid duplicates. Remember to URL-encode the filter in the query string. Pagination and the other query parameters are described in the reference.

How statuses appear

SCIM only knows whether a user is active. BreezeAuth’s statuses appear like this:

Status in BreezeAuth	active
Active	true
Inactive, Pending, Invite declined, Pending review	false

Update a user

Replace a user (PUT)

PUT /Users/{id} replaces the whole user with the body you send, which has the same format as for creation. Any attribute you leave out is cleared in BreezeAuth, and if active is left out, the user becomes Active. Send the complete user every time, or use PATCH to change only some attributes.

Change some attributes (PATCH)

PATCH /Users/{id} applies a list of operations, following the SCIM standard:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "title", "value": "Sales Director" },
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department",
      "value": "Commercial"
    },
    { "op": "remove", "path": "phoneNumbers[type eq \"mobile\"].value" }
  ]
}

Each operation has an op (add, replace or remove), a path and, except for remove, a value. The supported paths are:

Path	add / replace	remove
active	Yes	No
userName or emails[type eq "work"].value	Yes	No
name.givenName, name.familyName	Yes	No
displayName (split into first and last name)	Yes	No
externalId	Yes	Yes
title	Yes	Yes
phoneNumbers[type eq "work"].value, phoneNumbers[type eq "mobile"].value	Yes	Yes
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User: followed by employeeNumber, costCenter, organization, department, manager or manager.value	Yes	Yes

An add or replace operation can also leave out path and send an object as value, for example { "op": "replace", "value": { "active": false } }. In that form, BreezeAuth accepts active, userName, externalId, name, displayName, title and the Enterprise extension object. Addresses, secondary e-mails and photos can only be changed with PUT.

All the operations of a request are applied together: if one of them is invalid, nothing is changed.

Change a user’s e-mail address

Changing userName follows the same rules as in the admin console:

• Managed users: the new address must be on one of your verified domains. The person’s BreezeAuth account is updated too.
• Guests: the e-mail address can’t be changed, and the request fails with 400 Bad Request. To move a guest to a new address, create a new user and delete the old one.

Deactivate a user

To remove someone’s access while keeping their record, set active to false:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{ "op": "replace", "path": "active", "value": false }]
}

The user becomes Inactive, with the same effect as deactivating them in the admin console: a managed user can’t sign in to BreezeAuth at all, and a guest can no longer use your organization’s applications. Their groups and application assignments are kept. Set active back to true to restore access.

Delete a user

DELETE /Users/{id}

BreezeAuth returns 204 No Content. As when deleting in the admin console, the user is removed from all their groups and applications and, for a managed user, their BreezeAuth account is deleted too. This can’t be undone.

What SCIM can’t change

• Owners. Users with the Owner role can’t be changed or deleted through SCIM: the request fails with 401 Unauthorized. Manage them in the admin console.
• Roles. SCIM never gives or removes administrative roles.
• Statuses other than active and inactive. A provisioning system can’t put a user back to Pending or Pending review.
• Passwords, MFA and sessions. These belong to the person and to your organization’s account security tools.