# SCIM 2.0

## Enabling the SCIM API

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

```bash
UI_BAKERY_SCIM_TOKEN=YOUR_TOKEN
```

{% hint style="info" %}
UI Bakery doesn't provide authentication tokens by default, so you need to generate a token manually.
{% endhint %}

### 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

<mark style="color:blue;">`GET`</mark> `https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Users`

#### Path Parameters

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| workspace<mark style="color:red;">\*</mark> | String | UI Bakery workspace slug |

#### Query Parameters

| Name       | Type    | Description   |
| ---------- | ------- | ------------- |
| filter     | String  | Filter string |
| count      | Integer |               |
| startIndex | Integer |               |

{% tabs %}
{% tab title="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": "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"
          }
        ] 
      }
    ]
}
```

{% endtab %}
{% endtabs %}

### Get user by email

<mark style="color:blue;">`GET`</mark> `https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Users/{email}`

#### Path Parameters

| Name                                          | Type   | Description              |
| --------------------------------------------- | ------ | ------------------------ |
| {workspace}<mark style="color:red;">\*</mark> | String | UI Bakery workspace slug |
| email<mark style="color:red;">\*</mark>       | String | User email               |

{% tabs %}
{% tab title="200: OK " %}

```
{
  "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
    }
  ],
  ...
}
```

{% endtab %}
{% endtabs %}

### Create user

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | 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<mark style="color:red;">\*</mark>     | Array  | \["urn:ietf:params:scim:schemas:core:2.0:User"] |
| displayName<mark style="color:red;">\*</mark> | String | John Doe                                        |
| emails<mark style="color:red;">\*</mark>      | Array  | \[{ "value": "<user@example.com>"}]             |
| groups                                        | Array  | \[{"value": "ROLE\_ID"}]                        |

{% tabs %}
{% tab title="201: Created " %}

```
{
  "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
    }
  ],
  ...
}
```

{% endtab %}
{% endtabs %}

### Update user

<mark style="color:orange;">`PUT`</mark> `https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Users/{email}`

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

:warning: 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<mark style="color:red;">\*</mark>     | String | User email               |
| workspace<mark style="color:red;">\*</mark> | String | UI Bakery workspace slug |

#### Request Body

| Name                                          | Type    | Description                                                     |
| --------------------------------------------- | ------- | --------------------------------------------------------------- |
| schemas                                       | Array   | \["urn:ietf:params:scim:schemas:core:2.0:User"]                 |
| displayName<mark style="color:red;">\*</mark> | String  | John Doe 2                                                      |
| active<mark style="color:red;">\*</mark>      | Boolean | If `false` value is passed, user will be deleted from workspace |
| emails<mark style="color:red;">\*</mark>      | Array   | \[{ "value": "<user@example.com>"}]                             |
| groups                                        | Array   | \[{"value": "ROLE\_ID"}]                                        |

{% tabs %}
{% tab title="200: OK " %}

```
{
  "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
    }
  ],
  ...
}
```

{% endtab %}
{% endtabs %}

### Patch user

<mark style="color:purple;">`PATCH`</mark> `https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Users/{email}`

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

:warning: 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<mark style="color:red;">\*</mark>     | String | User email               |
| workspace<mark style="color:red;">\*</mark> | String | UI Bakery workspace slug |

#### Request Body

| Name                                         | Type  | Description                                              |
| -------------------------------------------- | ----- | -------------------------------------------------------- |
| schemas                                      | Array | \["urn:ietf:params:scim:api:messages:2.0:PatchOp"]       |
| Operations<mark style="color:red;">\*</mark> | Array | \[{"op":"replace","value":{"displayName":"John Doe 3"}}] |

{% tabs %}
{% tab title="200: OK " %}

```
{
  "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
    }
  ],
  ...
}
```

{% endtab %}
{% endtabs %}

### Delete user by email

<mark style="color:red;">`DELETE`</mark> `https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Users/test@example.com`

#### Path Parameters

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| workspace<mark style="color:red;">\*</mark> | String | UI Bakery workspace slug |
| email<mark style="color:red;">\*</mark>     | String | User email               |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}
{% endtabs %}

## Groups (UI Bakery roles) methods

### Get list of workspace roles

<mark style="color:blue;">`GET`</mark> `https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Groups`

#### Path Parameters

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| workspace<mark style="color:red;">\*</mark> | String | UI Bakery workspace slug |

#### Query Parameters

| Name       | Type    | Description   |
| ---------- | ------- | ------------- |
| filter     | String  | Filter string |
| count      | Integer |               |
| startIndex | String  |               |

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

{% endtab %}
{% endtabs %}

### Get role details by id

<mark style="color:blue;">`GET`</mark> `https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Groups/{id}`

#### Path Parameters

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| workspace<mark style="color:red;">\*</mark> | String | UI Bakery workspace slug |
| id<mark style="color:red;">\*</mark>        | String | UI Bakery Role id        |

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

{% endtab %}
{% endtabs %}

### Create role

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | String | UI Bakery workspace slug |

#### Request Body

| Name                                          | Type   | Description                                            |
| --------------------------------------------- | ------ | ------------------------------------------------------ |
| schemas<mark style="color:red;">\*</mark>     | Array  | \["urn:ietf:params:scim:schemas:core:2.0:Group"]       |
| displayName<mark style="color:red;">\*</mark> | String | New role                                               |
| roleType                                      | Enum   | `workspace` or `endUser`, Default value is `worksapce` |

{% tabs %}
{% tab title="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"
}
```

{% endtab %}
{% endtabs %}

### Update role

<mark style="color:orange;">`PUT`</mark> `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<mark style="color:red;">\*</mark>        | String | roleId                   |
| workspace<mark style="color:red;">\*</mark> | 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**                     |

{% tabs %}
{% tab title="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": "user2@example.com",
      "display": "John Doe 2",
    }
  ],
  "roleType": "workspace"
}
```

{% endtab %}
{% endtabs %}

### Patch role

<mark style="color:purple;">`PATCH`</mark> `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<mark style="color:red;">\*</mark>        | String | roleId                   |
| workspace<mark style="color:red;">\*</mark> | 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": "<user2@example.com>" } ] } }] |

{% tabs %}
{% tab title="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"
}
```

{% endtab %}
{% endtabs %}

### Delete role by id

<mark style="color:red;">`DELETE`</mark> `https://UI_BAKERY_INSTANCE/api/scim/v2/{workspace}/Groups/{id}`

#### Path Parameters

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| workspace<mark style="color:red;">\*</mark> | String | UI Bakery workspace slug |
| id<mark style="color:red;">\*</mark>        | String | Role id                  |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}
{% endtabs %}

## 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.