SCIM API

Smartflow SCIM API is a standard REST API that that operates on SCIM standard and allows external systems to exchange user identity information. It provides a minimum set of requirements from the SCIM specification to facilitate automation of user identities with most identity providers.

What is SCIM?

SCIM (System for Cross-Domain Identity Management) is an open standard for communication between Identity Management (IdM) systems and applications or services that authenticate and/or authorize through the IdM systems. The SCIM specification is designed to make the management of user identities easier in cloud-based applications and services. SCIM standard allows for the automation of provisioning user accounts to different systems.

The SCIM protocol defines a client and a server role. A client is usually an Identity Provider (IdP) like Microsoft Azure Active Directory, Auth0, Okta etc that contains the information on user identities. Smartflow SCIM API acts as the server. When new identities are added or existing identities modified in the client, they send a request to the server according to the SCIM protocol in order to sync the changes to Smartflow.

SCIM 2.0 is built on an object model where a Resource is the common denominator and all SCIM objects are derived from it. User and Group extend the common attributes from Resource.

For the scope of this document, the term SCIM refers to SCIM 2.0.

Environments

The Smartflow SCIM API can be consumed through standard HTTP calls to the server. The API is available at:

Environment	URL

Environment	URL
Acceptance	https://scim-uat.smartflowcloud.com/{yourdomain}/
Production	https://scim.smartflowcloud.com/{yourdomain}/

Users

A user is a person or a service that has a set of permissions to interact with Smartflow.

The Smartflow SCIM API can be used to manage the life cycle of a user in an organization. Common use cases are:

Click here to view API documentation on managing users.

User attributes

Each user has properties called attributes. The id attribute is assigned by the system and uniquely identifies the user in Smartflow. The username attribute must be provided when creating a user and uniquely identifies the user in the organization (domain group). It is recommended to use the user’s email as the username as most IdPs use this convention.

A user in SCIM is mapped to a user in the Smartflow database.

SCIM User attribute	Smartflow user property	Description

SCIM User attribute	Smartflow user property	Description
id		Unique identifier of the user. It is assigned by the system.
userName	Username	Unique name for the user in the organization. It is usually the same as the user’s email, and uniquely identifies a user within an organization (domain group). Can only contain alphanumeric characters, underscore (_), hyphen (-) and dot (.).
name honorificPrefix givenName middleName familyName formatted	Initials First name Middle name Last name Display name	Name components of the user. If displayName is not provided, it is by default set as: “<honorificPrefix> <givenName> <middleName> <familyName>”.
emails	Emails[primary eq “true”].value	Email address of the user. Note: As of version 1.0, the API supports only one email for the user, which must be a primary email.
groups		List of groups (roles) the user belongs to.
locale	Locale	Preferred language of the user. It follows ISO 639-1 standard for language codes. If not provided, the user’s locale is set to “en-US” as default.
active	IsActive	Boolean value (true or false) indicating whether the user is active. An inactive user cannot access the system. If not provided, “false” is set as the default value, indicating the user is inactive.
externalId	RefExternal	External identifier for the user. It can be the unique identifier of the user in the source system.
meta created lastModified		Timestamp when the user was created or last modified in ISO-8601 standard.

Groups

A group is a logical division of users. Members of the same group have similar permissions in Smartflow.

The Smartflow SCIM API can be used to manage users into groups. Common use cases are:

Click here to view API documentation on managing groups.

Group attributes

Each group has properties called attributes. The id attribute is assigned by the system and uniquely identifies the group in Smartflow. The displayName attribute must be provided when creating a group and uniquely identifies the group in the organization (domain group).

A group in SCIM is mapped to a role in the Smartflow database.

SCIM group attribute	Smartflow role property	Description

SCIM group attribute	Smartflow role property	Description
id		Unique identifier of the group. It is assigned by the system.
displayName	RoleName	Unique name for the group in the organization.
members		List of members (users) that belong to the group.
meta created lastModified		Timestamp when the user was created or last modified in ISO-8601 standard.

API documentation

An extensive documentation on the SCIM API is available here.

Here are a few quick links:

Errors reference

Code	Message	Description
400	{Attribute} is required.	A mandatory attribute was not provided in the request. See mandatory attributes for users and groups.
400	{Attribute} must be at least {limit} chars.	An attribute did not meet the minimum length criteria. See type and length requirements for attributes.
400	{Attribute} should not exceed {limit} chars.	An attribute exceeded the maximum length allowed. See type and length requirements for attributes.
400	{Attribute} is not valid.	An attribute is not in valid format. e.g. email is not in proper format, locale is not a valid code etc.
400	At least one primary email is required.	A user must have one primary email.
400	{Attribute} is immutable or readOnly.	An attribute sent in the request cannot be modified. This occurs when immutable attributes like id or readOnly attributes like meta.created are sent in the request.
401	Invalid access token.	Access token provided in the header is not proper or may have expired. Obtain a new access token if it has expired.
403	System roles cannot be modified.	System roles like Default, Builder and Maintenance cannot be modified.
404	{Resource} does not exist.	There is no resource in the database with the given id. This may occur due to incorrect id when you try to fetch a user or a group, or when you try to add or remove members from a group.
409	{Resource} already exists.	Resource you are trying to create already exists. In case of users, there may already exist a user with the given id or username. In case of groups, there may already exist a group with the displayName.
500	Internal server error.	An unexpected error occurred. Contact system administrator.