SCIM APIs: A beginner’s guide to enterprise SaaS provisioning

Exploring the system for cross-domain identity management (SCIM) — an open standard intended to make managing user identities in SaaS apps and services seamless via REST API.

Provisioning users and accounts across different software doesn’t have to take hours of manual work or understanding various different APIs, thanks to the SCIM standard that has been embraced by many of our favorite Enterprise tools and software. In the words of the Internet Engineering Task Force (IETF), SCIM aims to “make it fast, cheap, and easy to move users in to, out of, and around the cloud” via an easy-to-use REST API.

Let’s take a closer look at what SCIM is, and why it’s useful. 🔍

The SCIM data model explained
SCIM 2.0 is built around a model that uses a Resource object. SCIM includes several different Resource types — primarily focused on User and Group types.

(Source: simplecloud.info)

User
User data is encoded as a SCIM object in JSON according to a uniform scheme. Users would typically represent users in a company or organization.

Group
Group data is similarly encoded as a SCIM object in JSON. Groups would typically represent teams, business units, streams, etc. in a company or organization. Groups are commonly used to delineate users into different access levels or security groups.

Why use SCIM?
It’s simple! SCIM, as a trusted standard, brings uniformity to common administrative processes when it comes to managing the user and group life cycles for a company or organization. A SCIM REST API endpoint will always follow the standard SCIM conventions, so you can manage users and groups in the same way for one organization as you would for another.

SCIM makes provisioning enterprise users and groups simple!

For example, imagine you are a large Enterprise who leverages software like Teams or Zoom for video conferencing, and Miro for visual collaboration. Each of these organizations maintain a SCIM REST API for managing users/groups — so, if a new employee starts at your company and you need to quickly provision them both a video conferencing account and a Miro account, you can do so in a very similar way for both pieces of software (by making requests to their respective SCIM endpoints).

Instead of working with each organization’s custom API endpoints for managing users and spending time understanding how they’re designed, you can work directly with a convention you’re already familiar with, SCIM. 😉

Check out these examples from Miro, Slack, and Zoom, for example.

In short, since it’s standardized, you can manage users and groups in a familiar programmatic way across tools and organizations.

SCIM also supports SSO users, which is why it’s popular for Enterprise-level provisioning of users and accounts.

SCIM in context: Miro REST API
Let’s take a closer look with a concrete example: creating a user in Miro, via our SCIM 2.0 REST API.

Request:

POST https://miro.com/api/v1/scim/Users
Body:
{
    "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName":"test@miro.com",
    "name":{
        "familyName":"Smith",
        "givenName":"John"
    }
}

Response:

200 OK
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "3074457345620139606",
    "meta": {
        "resourceType": "User",
        "location": "https://miro.com/api/v1/scim/Users/3074457345620139606"
    },
    "userName": "test@miro.com",
    "name": {
        "familyName": "Smith",
        "givenName": "John"
    },
    "displayName": "John Smith",
    "active": true,
    "emails": [
        {
            "value": "test@miro.com",
            "display": "test@miro.com",
            "primary": true
        }
    ]
}

It seems straightforward enough, right? Here are some fundamental SCIM properties to highlight in this example:

• Resource URI will always be /User for users provisioned via a SCIM API
• Meta data will always include a reference to the resourceType
• userName, displayName, emails, are all examples of SCIM standard fields

In addition to these properties, another great benefit of SCIM endpoints is that they offer discovery support. This means that you can call these supplementary endpoints to retrieve supported features and get specific attribute details.

Explore SCIM and enterprise management in Miro
Want to test Miro’s SCIM API? Get started with our SCIM introduction and make API calls directly from a Miro Enterprise account.

You can also manage users and teams in Miro with an even higher level of customization by leveraging our comprehensive suite of Enterprise REST APIs. Just make sure you handle these prerequisites first:

• Sign up for an Enterprise plan in Miro
• Enable SSO
• Create a developer team under your Enterprise organization

Once you’ve got this handled, get started in less than 3 minutes by following our API Quickstart Guide, or reference our Enterprise Sample App!

Demo: Exploring Miro’s SCIM and Enterprise APIs

Did you like seeing how you can leverage Miro’s REST APIs? For more inspiration or questions, follow along with our Developer Community on YouTube, GitHub, and Discord.