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

{
    "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": "[email protected]",
        "meta": {
          "resourceType": "User",
          "created": "2023-04-12T00:00:00+03:00",
          "lastModified": "2023-04-12T00:00:00+03:00",
          "location": "/scim/v2/workspace/Users/[email protected]"
        },
        "userName": "[email protected]",
        "name": {
          "formatted": "User Name",
          "familyName": "",
          "givenName": "",
          "middleName": ""
        },
        "displayName": "User Name",
        "active": true,
        "emails": [
          {
            "value": "[email protected]"
          }
        ],
        "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

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "[email protected]",
  "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": "[email protected]",
  "name": {
    "formatted": "User Name",
    "familyName": "",
    "givenName": "",
    "middleName": "",
    "honorificPrefix": null,
    "honorificSuffix": null
  },
  "displayName": "User Name",
  "emails": [
    {
      "value": "[email protected]",
      "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": "[email protected]"}]

groups

Array

[{"value": "ROLE_ID"}]

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "[email protected]",
  "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": "[email protected]",
  "name": {
    "formatted": "John Doe",
    "familyName": "",
    "givenName": "",
    "middleName": "",
    "honorificPrefix": null,
    "honorificSuffix": null
  },
  "displayName": "John Doe",
  "emails": [
    {
      "value": "[email protected]",
      "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": "[email protected]"}]

groups

Array

[{"value": "ROLE_ID"}]

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "[email protected]",
  "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": "[email protected]",
  "name": {
    "formatted": "John Doe 2",
    "familyName": "",
    "givenName": "",
    "middleName": "",
    "honorificPrefix": null,
    "honorificSuffix": null
  },
  "displayName": "John Doe 2",
  "emails": [
    {
      "value": "[email protected]",
      "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"}}]

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "[email protected]",
  "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": "[email protected]",
  "name": {
    "formatted": "John Doe 3",
    "familyName": "",
    "givenName": "",
    "middleName": "",
    "honorificPrefix": null,
    "honorificSuffix": null
  },
  "displayName": "John Doe 3",
  "emails": [
    {
      "value": "[email protected]",
      "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/[email protected]

Path Parameters

Name
Type
Description

workspace*

String

UI Bakery workspace slug

email*

String

User email

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

{
  "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": "[email protected]",
          "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

{
  "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": "[email protected]",
      "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

{
  "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

{
  "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": "[email protected]",
      "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": "[email protected]" } ] } }]

{
  "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

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.

Last updated

Was this helpful?