Sign InRoadmapRelease notes

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

Query Parameters

{
    "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": "user@example.com",
        "meta": {
          "resourceType": "User",
          "created": "2023-04-12T00:00:00+03:00",
          "lastModified": "2023-04-12T00:00:00+03:00",
          "location": "/scim/v2/workspace/Users/user@example.com"
        },
        "userName": "user@example.com",
        "name": {
          "formatted": "User Name",
          "familyName": "",
          "givenName": "",
          "middleName": ""
        },
        "displayName": "User Name",
        "active": true,
        "emails": [
          {
            "value": "user@example.com"
          }
        ],
        "groups": [
          {
            "value": "ardFdxe8tG",
            "display": "admin",
            "type": "workspace"
          }
        ] 
      }
    ]
}

Get user by email

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

Path Parameters

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

Query Parameters

Request Body

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "user@example.com",
  "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": "user@example.com",
  "name": {
    "formatted": "John Doe",
    "familyName": "",
    "givenName": "",
    "middleName": "",
    "honorificPrefix": null,
    "honorificSuffix": null
  },
  "displayName": "John Doe",
  "emails": [
    {
      "value": "user@example.com",
      "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 groups aren't provided then no changes applied to user roles.

Accepts JSON representation of SCIM UserResource.

Path Parameters

Request Body

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

Accepts JSON representation of SCIM Patch Operations array.

Path Parameters

Request Body

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

Path Parameters

Groups (UI Bakery roles) methods

Get list of workspace roles

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

Path Parameters

Query Parameters

{
  "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": "user@example.com",
          "display": "John Doe"
        }
      ],
      "roleType": "workspace"
    },
    ...
  ]
}

Get role details by id

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

Path Parameters

{
  "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": "user@example.com",
      "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

Request Body

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

Request Body

{
  "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": "user2@example.com",
      "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

Request Body

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

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.

PreviousEmbeddingNextInstance API

Last updated

© 2024 UI Bakery