SCIM 2.0

The SCIM API allows to manage user accounts within the UI Bakery workspace.

Enabling the SCIM API

To enable the SCIM API on your instance, you will need to provide an authentication token via an environment variable:

UI_BAKERY_SCIM_TOKEN=YOUR_TOKEN

UI Bakery doesn't provide authentication tokens by default, so you need to generate a token manually.

Making Requests to the UI Bakery SCIM API

To interact with the UI Bakery SCIM API, you need to make requests to the following URL where UI_BAKERY_INSTANCE is your domain and {workspace} is your UI Bakery workspace slug.

http(s)://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}

To authenticate your requests, include the Authorization: Bearer TOKEN header with the value provided in UI_BAKERY_SCIM_TOKEN env variable.

Supported Operations with the SCIM API

The SCIM API in UI Bakery provides a range of operations to synchronize user accounts between your Identity Provider (IDP) and UI Bakery. By utilizing the SCIM API, you can manage Users and Roles within your UI Bakery workspace. The following operations are supported

• Create new users in the workspace

• Update user attributes

• Remove users from the workspace

• Create roles in the workspace

• Rename roles

• Delete roles

• Assign roles to users

Reference

User methods:

Get list of users in workspace

GET https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Users

Path Parameters

Name	Type	Description
workspace*	String	UI Bakery workspace slug

Query Parameters

Name	Type	Description
filter	String	Filter string
count	Integer
startIndex	Integer

200: OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 0,
    "Resources": [
      {
        "schemas": [
          "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "id": "[e-mail]",
        "meta": {
          "resourceType": "User",
          "created": "2023-04-12T00:00:00+03:00",
          "lastModified": "2023-04-12T00:00:00+03:00",
          "location": "/scim/v2/workspace/Users/[e-mail]"
        },
        "userName": "[e-mail]",
        "name": {
          "formatted": "User Name",
          "familyName": "",
          "givenName": "",
          "middleName": ""
        },
        "displayName": "User Name",
        "active": true,
        "emails": [
          {
            "value": "[e-mail]"
          }
        ],
        "groups": [
          {
            "value": "ardFdxe8tG",
            "display": "admin",
            "type": "workspace"
          }
        ] 
      }
    ]
}

Get user by email

GET https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Users/{email}

Path Parameters

Name	Type	Description
{workspace}*	String	UI Bakery workspace slug
email*	String	User email

200: OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "[e-mail]",
  "externalId": null,
  "meta": {
    "resourceType": "User",
    "created": "2023-04-11T21:00:00.000+00:00",
    "lastModified": "2023-04-11T21:00:00.000+00:00",
    "location": null,
    "version": null
  },
  "userName": "[e-mail]",
  "name": {
    "formatted": "User Name",
    "familyName": "",
    "givenName": "",
    "middleName": "",
    "honorificPrefix": null,
    "honorificSuffix": null
  },
  "displayName": "User Name",
  "emails": [
    {
      "value": "[e-mail]",
      "display": null,
      "type": null,
      "primary": null
    }
  ],
  "groups": [
    {
      "value": "ardFdxe8tG",
      "display": "admin",
      "type": "workspace",
      "$ref": null
    }
  ],
  ...
}

Create user

POST https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Users

Creates a new user in the workspace. The new user has a default user role, If groups aren't provided. New user should sign up to assign a password.

Accepts JSON representation of SCIM UserResource.

Path Parameters

Name	Type	Description
workspace*	String	UI Bakery workspace slug

Query Parameters

Name	Type	Description
sendEmail	Boolean	If true then invitation email will be sent.

Request Body

Name	Type	Description
schemas*	Array	["urn:ietf:params:scim:schemas:core:2.0:User"]
displayName*	String	John Doe
emails*	Array	[{ "value": "[e-mail]"}]
groups	Array	[{"value": "ROLE_ID"}]

201: Created

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "[e-mail]",
  "externalId": null,
  "meta": {
    "resourceType": "User",
    "created": "2023-04-11T21:00:00.000+00:00",
    "lastModified": "2023-04-11T21:00:00.000+00:00",
    "location": null,
    "version": null
  },
  "userName": "[e-mail]",
  "name": {
    "formatted": "John Doe",
    "familyName": "",
    "givenName": "",
    "middleName": "",
    "honorificPrefix": null,
    "honorificSuffix": null
  },
  "displayName": "John Doe",
  "emails": [
    {
      "value": "[e-mail]",
      "display": null,
      "type": null,
      "primary": null
    }
  ],
  "groups": [
    {
      "value": "ardFdxe8tG",
      "display": "user",
      "type": "endUser",
      "$ref": null
    }
  ],
  ...
}

Update user

PUT https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Users/{email}

Updates user, supports changes for name, email, and other fields.

⚠️ If the active attribute is set to false , the user will be removed from the workspace and will be immediately signed out.

If groups aren't provided then no changes applied to user roles.

Accepts JSON representation of SCIM UserResource.

Path Parameters

Name	Type	Description
email*	String	User email
workspace*	String	UI Bakery workspace slug

Request Body

Name	Type	Description
schemas	Array	["urn:ietf:params:scim:schemas:core:2.0:User"]
displayName*	String	John Doe 2
active*	Boolean	If false value is passed, user will be deleted from workspace
emails*	Array	[{ "value": "[e-mail]"}]
groups	Array	[{"value": "ROLE_ID"}]

200: OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "[e-mail]",
  "externalId": null,
  "meta": {
    "resourceType": "User",
    "created": "2023-04-11T21:00:00.000+00:00",
    "lastModified": "2023-04-11T21:00:00.000+00:00",
    "location": null,
    "version": null
  },
  "userName": "[e-mail]",
  "name": {
    "formatted": "John Doe 2",
    "familyName": "",
    "givenName": "",
    "middleName": "",
    "honorificPrefix": null,
    "honorificSuffix": null
  },
  "displayName": "John Doe 2",
  "emails": [
    {
      "value": "[e-mail]",
      "display": null,
      "type": null,
      "primary": null
    }
  ],
  "groups": [
    {
      "value": "ardFdxe8tG",
      "display": "user",
      "type": "endUser",
      "$ref": null
    }
  ],
  ...
}

Patch user

PATCH https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Users/{email}

Updates user, supports changes for name, email, and other fields.

⚠️ If the active attribute is set to false , the user will be removed from the workspace and will be immediately signed out.

Accepts JSON representation of SCIM Patch Operations array.

Path Parameters

Name	Type	Description
email*	String	User email
workspace*	String	UI Bakery workspace slug

Request Body

Name	Type	Description
schemas	Array	["urn:ietf:params:scim:api:messages:2.0:PatchOp"]
Operations*	Array	[{"op":"replace","value":{"displayName":"John Doe 3"}}]

200: OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "[e-mail]",
  "externalId": null,
  "meta": {
    "resourceType": "User",
    "created": "2023-04-11T21:00:00.000+00:00",
    "lastModified": "2023-04-11T21:00:00.000+00:00",
    "location": null,
    "version": null
  },
  "userName": "[e-mail]",
  "name": {
    "formatted": "John Doe 3",
    "familyName": "",
    "givenName": "",
    "middleName": "",
    "honorificPrefix": null,
    "honorificSuffix": null
  },
  "displayName": "John Doe 3",
  "emails": [
    {
      "value": "[e-mail]",
      "display": null,
      "type": null,
      "primary": null
    }
  ],
  "groups": [
    {
      "value": "ardFdxe8tG",
      "display": "user",
      "type": "endUser",
      "$ref": null
    }
  ],
  ...
}

Delete user by email

DELETE https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Users/[e-mail]

Path Parameters

Name	Type	Description
workspace*	String	UI Bakery workspace slug
email*	String	User email

200: OK

Groups (UI Bakery roles) methods

Get list of workspace roles

GET https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Groups

Path Parameters

Name	Type	Description
workspace*	String	UI Bakery workspace slug

Query Parameters

Name	Type	Description
filter	String	Filter string
count	Integer
startIndex	String

200: OK

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 3,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "bdeM5DxR8tG",
      "meta": {
        "created": "2023-06-15T12:49:42+03:00",
        "resourceType": "Group",
        "location": "/scim/v2/workspace/Groups/ddMfWdR8tG"
      },
      "displayName": "admin",
      "members": [
        {
          "value": "[e-mail]",
          "display": "John Doe"
        }
      ],
      "roleType": "workspace"
    },
    ...
  ]
}

Get role details by id

GET https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Groups/{id}

Path Parameters

Name	Type	Description
workspace*	String	UI Bakery workspace slug
id*	String	UI Bakery Role id

200: OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "bdeM5DxR8tG",
  "externalId": null,
  "meta": {
    "resourceType": null,
    "created": "2023-06-15T09:49:42.000+00:00",
  },
  "displayName": "admin",
  "members": [
    {
      "value": "[e-mail]",
      "display": "John Doe",
    }
  ],
  "roleType": "workspace"
}

Create role

POST https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Groups

Creates a new role in workspace, new role has no permissions to projects and datasources.

Accepts JSON representation of SCIM GroupResource.

Path Parameters

Name	Type	Description
workspace*	String	UI Bakery workspace slug

Request Body

Name	Type	Description
schemas*	Array	["urn:ietf:params:scim:schemas:core:2.0:Group"]
displayName*	String	New role
roleType	Enum	workspace or endUser, Default value is worksapce

201: Created

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "bdeM5DxR8tG",
  "externalId": null,
  "meta": {
    "resourceType": null,
    "created": "2023-06-15T09:49:42.000+00:00",
  },
  "displayName": "New Role",
  "members": [],
  "roleType": "workspace"
}

Update role

PUT https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Groups/{id}

Updates role in UI Bakery, accepts JSON representation of SCIM Patch Operations. With patch operation you can assign roles to user.

Accepts JSON representation of SCIM GroupResource.

Path Parameters

Name	Type	Description
id*	String	roleId
workspace*	String	UI Bakery workspace slug

Request Body

Name	Type	Description
schemas	Array	["urn:ietf:params:scim:schemas:core:2.0:Group"]
displayName	String	New role 3
roleType	Enum	workspace or endUser

200: OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "bdeM5DxR8tG",
  "externalId": null,
  "meta": {
    "resourceType": null,
    "created": "2023-06-15T09:49:42.000+00:00",
  },
  "displayName": "New Role 3",
  "members": [
    {
      "value": "[e-mail]",
      "display": "John Doe 2",
    }
  ],
  "roleType": "workspace"
}

Patch role

PATCH https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Groups/{id}

Updates role in UI Bakery.

Accepts JSON representation of SCIM Patch Operations array.

Path Parameters

Name	Type	Description
id*	String	roleId
workspace*	String	UI Bakery workspace slug

Request Body

Name	Type	Description
schemas	Array	["urn:ietf:params:scim:schemas:core:2.0:Group"]
Operations	Array	[{"op":"replace","value":{"members":[ {"value": "[e-mail]" } ] } }]

200: OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "bdeM5DxR8tG",
  "externalId": null,
  "meta": {
    "resourceType": null,
    "created": "2023-06-15T09:49:42.000+00:00",
  },
  "displayName": "New Role 3",
  "members": [],
  "roleType": "workspace"
}

Delete role by id

DELETE https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Groups/{id}

Path Parameters

Name	Type	Description
workspace*	String	UI Bakery workspace slug
id*	String	Role id

200: OK

Example of integration with Okta

In this example, we will show you how to synchronize users and groups from Okta to UI Bakery.

Create a new application

1. Go to the Applications section in the Okta Admin account

2. Click on Browse App Catalog

3. Search for "SCIM 2.0 Test App (OAuth Bearer Token)"

4. Click Add integration

5. Enter a name for your integration

6. Choose SAML in Sign-On Options

7. In Credentials Details select Email for Application username format

8. Click Done

Connect integration with UI Bakery

1. Select Provisioning tab

2. Click Configure API Integration and enable API Integration

3. Specify the Base URL as https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace} where UI_BAKERY_INSTANCE is your domain name and workspace is equal to the UI Bakery workspace slug

4. Enter the OAuth Bearer Token with a value the same as the UI Bakery env variable UI_BAKERY_SCIM_TOKEN

5. Click test and then connect the integration

Configure integration

1. In the Provisioning tab select To App section and enable the following Create Users, Update User Attributes, Deactivate Users

2. In the Assignments tab assign users or groups. Note that assigned groups may not synchronize with UI Bakery roles. Refer to Okta documentation for using other Okta groups for the Groups Push feature.