About this Feature
The Stensul platform REST API enables customers to manage the provisioning of users via the SCIM protocol. Learn more about the SCIM protocol here.
Authentication
The Stensul API leverages an OAuth 2.0 Server-to-Server connection to authenticate API calls. This is an industry standard method that enables two platforms to securely authenticate with each other without involving any user interaction. Learn more about OAuth Server-to-Server authentication here.
Before your can access the Stensul API, you must first create an API Connection in the Stensul platform. This connection is used to generate a Client ID and Client Secret that is needed when authenticating with the Stensul API. You must also set one or more egress IP addresses in the Stensul allowlist. To create and manage your API connections, and IP address allowlist, follow our API Connections EUD here.
About the SCIM Protocol
SCIM (System for Cross-domain Identity Management) is an API standard that was established specifically for standardizing how 3rd party user identity management platform in cloud-based applications work so they can easily connect to platforms and services like Stensul. Learn more about the SCIM API specification for user management here.
The SCIM protocol is very prescriptive and only applies to specific parts of the Stensul platform API. For example, “Libraries“ is not a concept that is a part of the SCIM specification and instead the Libraries object is used in conjunction with the SCIM specification to support user provisioning via API in Stensul.
SCIM Specific API Objects
SCIM: User Provisioning
In the SCIM specification, the user provisioning object supports all common REST API operations.
POST - Create a new user
GET - Retrieve all available information for a specific user
GET - Retrieve all available information for a list of users
PUT - Update all available information for a specific user
PATCH - Update some fields of a specific user
DEL - Delete a specific user
Disabling a User
Stensul’s API supports disabling a user without deleting the entry via the active attribute. This is not a feature that is accessible in the Stensul UI, but is availalbe via the API.
active (boolean): Indicates whether the user is active and can either be true or false
A user can also be disabled via the DELETE (link) endpoint. Any user deletions are “soft deletes“ and can be retrieved with the POST (link) endpoint where the call would need to use the email address of the deleted user. Note: Any soft deleted values in Stensul e.g. users, will not appear in any GET endpoints.
SCIM: Group Provisioning
In the SCIM specification, certain terminology is required and therefore does not match 1:1 in the Stensul platform. For example, the term “Group“ in SCIM refers to the the concept of Stensul Roles. Note that “Groups“ in this API object does not refer to the Stensul concept “Workflow User Groups”.
The group provisioning object supports all common REST API operations.
POST - Create a new group (Stensul role) - Coming Soon!
GET - Retrieve all available information for a specific group (Stensul role)
GET - Retrieve all available information for a list of groups (Stensul role)
PUT - Update all available information for a specific group (Stensul role) - Coming Soon!
PATCH - Update some fields of a specific group (Stensul role) - Coming Soon!
DEL - Delete a specific group (Stensul role) - Coming Soon!
SCIM Discovery Objects
To simplify usage, the SCIM specification supports three objects to discover supported features and specific attribute details:
Libraries Object
The libraries object in the Stensul API is an example of an additional SCIM resource. It is not part of the SCIM specification, but it is supported via a special “additional resource” designation.
Stensul libraries are an important part of creating and managing both users and roles in Stensul.
The Library object is limited and at this time only supports:
GET - Retrieve all available information for a list of libraries