SCIM API reference

This page is technical. It describes the BreezeAuth SCIM 2.0 API for the developers and teams who configure a provisioning system or build their own SCIM client. BreezeAuth follows RFC 7643 (schemas) and RFC 7644 (protocol), with the scope and limits described here. What each operation does to users and groups is explained in Provision users and Provision groups.

Base URL and endpoints

Every organization has its own base URL. See Find your SCIM base URL.

https://api.breezeauth.com/organizations/<organization ID>/scim/v2

Method	Path	Description
GET	/ServiceProviderConfig	The features this SCIM server supports.
GET	/ResourceTypes, /ResourceTypes/{name}	The resource types: User and Group.
GET	/Schemas, /Schemas/{id}	The core User, Enterprise User and core Group schemas.
GET	/Users	List and filter users.
POST	/Users	Create a user.
GET	/Users/{id}	Read a user.
PUT	/Users/{id}	Replace a user.
PATCH	/Users/{id}	Change some attributes of a user.
DELETE	/Users/{id}	Delete a user.
GET	/Groups	List and filter groups.
POST	/Groups	Create a group.
GET	/Groups/{id}	Read a group with its direct members.
PUT	/Groups/{id}	Replace a group and its members.
PATCH	/Groups/{id}	Rename a group, or add or remove members.
DELETE	/Groups/{id}	Delete a group without members.

/Bulk and /Me are not available.

Authentication

Every request must carry an access token of a service user with the SCIM Provisioner role, in the Authorization header:

Authorization: Bearer <access token>

Tokens are obtained from https://api.breezeauth.com/oauth/token with the OAuth 2.0 client credentials grant and the service user’s credential. They are short-lived: request a new one before expires_in runs out, or when a request returns 401 Unauthorized. See Obtain access tokens for the request format and code examples.

All the controls that apply to service users apply to SCIM requests too: the credential and the service user must be active, and the request must come from an allowed network and country if your organization restricts them.

Requests and responses

• Send request bodies as JSON, with Content-Type: application/scim+json or application/json.
• Responses use Content-Type: application/scim+json.
• The schemas attribute is optional in requests. BreezeAuth always includes it in responses.
• Successful POST requests return 201 Created and the address of the new resource in the Location header. Successful DELETE requests return 204 No Content with no body.
• Dates in meta.created and meta.lastModified are in ISO 8601 format and UTC.

List and filter

GET /Users and GET /Groups return a ListResponse:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 128,
  "startIndex": 1,
  "itemsPerPage": 50,
  "Resources": [{ "id": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d", "userName": "[email protected]", "…": "…" }]
}

Query parameter	Description
filter	One equality expression. See below.
startIndex	The 1-based position of the first result. Default 1.
count	How many results per page. Default 50. The maximum is filter.maxResults in /ServiceProviderConfig; larger values are reduced to it.

Filters

BreezeAuth supports a single equality (eq) expression on these attributes:

Resource	Attributes	Example
Users	userName, externalId	userName eq "[email protected]"
Groups	displayName, externalId	displayName eq "Sales Team"

Escape double quotes and backslashes in the value with a backslash, and URL-encode the whole filter in the query string. Other operators (co, sw, gt…), and, or and not are refused with 400 Bad Request and scimType invalidFilter.

Pagination

Results are returned in pages of count items. A page always starts at a multiple of count, plus one: with count=50, pages start at 1, 51, 101 and so on. If you ask for another startIndex, BreezeAuth returns the page that contains it, and the startIndex of the response tells you where that page actually starts. To read every result, start at 1 and add itemsPerPage to startIndex until you have totalResults items.

GET /Groups doesn’t include members. Read each group with GET /Groups/{id} to get them.

Select attributes

Use attributes to return only some attributes, or excludedAttributes to leave some out. Both take a comma-separated list and can’t be used in the same request. They work on every request that returns users or groups, including POST, PUT and PATCH.

GET /Users?attributes=userName,name.givenName,active
GET /Users?excludedAttributes=urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Sub-attributes use a dot, as in name.givenName. Attributes of the Enterprise extension use the full schema URN as a prefix, as in urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department. schemas, id and meta are always returned.

Errors

Errors follow the SCIM error format:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "email_already_used"
}

Status	scimType	Meaning
400 Bad Request	invalidSyntax	The body isn’t a valid SCIM message, for example a PATCH without Operations.
400 Bad Request	invalidValue	A value is missing or invalid, such as a missing userName, a member without a valid type, or an e-mail change BreezeAuth doesn’t allow.
400 Bad Request	invalidFilter	The filter isn’t supported. See Filters.
400 Bad Request	invalidPath	The PATCH path isn’t supported.
400 Bad Request	mutability	The attribute can’t be removed, such as active or userName.
400 Bad Request	tooMany	The group has more direct members than SCIM can return.
401 Unauthorized		The token is missing, invalid or expired; the credential or the service user is inactive; the role doesn’t allow the operation; the request comes from a network outside your network zones; or the user is an Owner.
403 Forbidden		The request comes from a country your organization doesn’t allow.
404 Not Found		The user, group, member or schema doesn’t exist in this organization.
409 Conflict	uniqueness	Another user already has this userName or externalId, or another group already has this externalId.
409 Conflict		The group still has members and can’t be deleted.
429 Too Many Requests		Too many requests. See Rate limits.
500 Internal Server Error		An unexpected error. Retry later; if it persists, contact BreezeAuth support.

detail holds a short code that says exactly what went wrong. The most common ones:

detail	Meaning
scim_user_name_required	userName is missing or empty.
scim_group_display_name_required	displayName is missing or empty.
scim_member_type_not_supported	A member’s type is missing, or isn’t User or Group.
scim_value_invalid	A value has the wrong type or format, for example active that isn’t a boolean.
scim_filter_not_supported	The filter uses an operator or an attribute that isn’t supported.
scim_attribute_path_invalid	The PATCH path isn’t supported, or the attribute can’t be removed.
scim_operation_invalid	A PATCH has no operations, or an operation isn’t add, replace or remove.
scim_group_members_limit_exceeded	The group has too many direct members to be returned through SCIM.
email_already_used	Another user of the organization already has this e-mail address.
scim_external_id_already_used	Another user, or for a group another group, already has this externalId.
email_address_of_guest_membership_cannot_be_updated	Guests’ e-mail addresses can’t be changed.
email_address_of_verified_user_to_unverified_domain_cannot_be_updated	A managed user’s e-mail can only move to another verified domain.
cannot_delete_group_with_assignments	The group still has members.

Rate limits

SCIM requests are limited per access token:

Window	Requests
1 second	50
10 seconds	400
30 seconds	1,500
1 minute	4,000

Above these limits, BreezeAuth answers 429 Too Many Requests. Wait a little and retry, increasing the wait after each new 429. Most provisioning systems do this on their own.

Supported features

GET /ServiceProviderConfig describes these capabilities in the standard format:

Feature	Supported
patch	Yes
filter	Yes, equality only. maxResults is the largest page size.
bulk	No
sort	No
etag	No
changePassword	No
authenticationSchemes	OAuth Bearer Token