SCIM

Manage the access granted to your users using the SCIM API.

SCIM Provisioning

The SCIM API is used by SCIM-enabled Identity Providers (IdPs) to automate provisioning and manage access for user accounts and teams (groups). The SMSByrd API is based on version 2.0 of the SCIM standard. The SCIM endpoint that an IdP should use is: https://expectr.io/api/scim/.

The SCIM API is only available to customers with an Enterprise plan, with Enterprise SSO enabled.

Authentication

To authenticate with the SMSByrd SCIM API, you must first create an account-level API key. As with all other authenticated calls to the SMSByrd API, this key must be passed using HTTP Basic Auth. Learn more about API authentication in our API reference.

SCIM user attributes

The following table maps SCIM attributes to the relevant fields that SMSByrd uses. Most of these profile fields are exposed directly in a person’s profile in the SMSByrd Dashboard:

NAME	TYPE	DESCRIPTION
displayName	string	The full name of the user. When provisioning a user, the name attributes are preferred to displayName.
name.givenName	string	The first name of the user.
name.familyName	string	The last name of the user.
emails	array	Whilst this is a list of user emails, SMSByrd only uses one, which will be associated with their SMSByrd account. If SMSByrd finds an email marked as primary (or one that is marked as the user’s “work” email address) then this will be used. Otherwise, the first email in the list will be selected.
userName	string	The email address associated with the SMSByrd user. May be used to set the email address for a user, if not set via the emails array.
id	string	Identifier generated by the SMSByrd SCIM endpoint.
externalId	string	This identifier is generated by the SAML provider, and is used as a unique ID by the SAML provider to match against a SMSByrd user. You can find the externalID for a user either at the SAML provider, or using the List SCIM provisioned identities endpoint and filtering on other known attributes, such as a user’s GitHub username or email address.
active	boolean	Indicates whether the identity is active (true) or should be deprovisioned (false).

List users

GET: https://expectr.io/api/scim/Users

Retrieves a paginated list of all users. If you provide the filter parameter, the resources for all matching provisioned users are returned.

Query parameters

startIndex: Integer

Used for pagination: the index of the first result to return.

count: Integer

Used for pagination: the number of results to return.

filter: String

Filters results using the equals query parameter operator (eq). You can only filter results that are equal to the userName. For example, to search for an identity with the userName bob@yourdomain.com, you would use this query: ?filter=userName%20eq%20"bob@yourdomain.com".

Provision a user

POST: https://expectr.io/api/scim/Users

Creates a new user. Must include the at least one email address. If an email address is marked as primary, it will be used.

This is an example request body for a typical provisioning request. In this example you@work.com will be used as it is marked as the primary email address (it would also have been used because it has the type work):

Retrieve a user

GET: https://expectr.io/api/scim/Users/{scim_user_id}

Returns the attributes of an existing user.

Update a user

PUT: https://expectr.io/api/scim/Users/{scim_user_id}

Updates an existing user resource, overwriting all values for a user even if an attribute is empty or not provided. If an attribute that had been set previously is left blank during a PUT operation, the new value will be blank in accordance with the data type of the attribute and the storage provider.

Delete a user

DELETE: https://expectr.io/api/scim/Users/{scim_user_id} Deletes a user from SMSByrd

Groups (Teams)

SCIM groups are mapped to SMSByrd “Teams”, which can be used for organizing users in logical divisions across a workspace, such as by team or affinity.

NAME	TYPE	DESCRIPTION
displayName	string	The team (group) name.
members	array	Users that are assigned to this team (group).

List groups

GET: https://expectr.io/api/scim/Groups

Returns a paginated list of groups.

Retrieve a single group

GET: https://expectr.io/api/scim/Groups/{scim_group_id}

Retrieves a single group resource.

Create a group

POST: https://expectr.io/api/scim/Groups

Must include the displayName attribute (as defined in the schema specification). Users can be added to the group during creation by supplying their ID values in the members array attribute.

Here is an example of a typical request body for provisioning a new group:

Update an existing group

PUT: https://expectr.io/api/scim/Groups/{scim_group_id}

Updates an existing group resource, overwriting all values for a group even if an attribute is empty or not provided. If an attribute that had been set previously is left blank during a PUT operation, the new value will be blank in accordance with the data type of the attribute and the storage provider.

Delete a single SCIM group

DELETE: https://expectr.io/api/scim/Groups/{scim_group_id}

Deletes an existing group.

SCIM Provisioning​

Authentication​

SCIM user attributes​

List users​

Query parameters​

Provision a user​

Retrieve a user​

Update a user​

Delete a user​

Groups (Teams)​

List groups​

Create a group​

Update an existing group​

Delete a single SCIM group​