> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM user provisioning

> Provision and deprovision Oleria workspace users and groups automatically from your identity provider using the SCIM 2.0 API.

Provision and deprovision Oleria workspace users and groups automatically from your identity provider (IdP) or any System for Cross-domain Identity Management (SCIM) 2.0 client, instead of managing each user by hand in **Manage Users**. Oleria exposes a SCIM 2.0 API so your IdP can create users, assign roles, manage group membership, and remove access as your directory changes.

This page covers how to authenticate to the SCIM API, how Oleria maps SCIM users and groups to its role-based access control (RBAC) model, and the supported user, group, and service provider endpoints.

<Note>
  This page covers how to provision workspace users. To provision reviewers for access review campaigns and access requests, use the separate governance endpoint documented in [SCIM reviewer provisioning](/governance/scim-reviewer-provisioning).
</Note>

## Prerequisites

* Administrator access to your Oleria workspace.
* The SCIM client credentials for your workspace, found in **Settings → SCIM Configuration**.
* A SCIM 2.0 client, such as your IdP's outbound provisioning feature, that can send a bearer token on every request.

## Authenticate to the SCIM API

The SCIM API uses the same OAuth 2.0 Client Credentials flow as the rest of the Oleria API. Oleria pre-creates a dedicated set of SCIM client credentials for your workspace, so you do not need to create an OAuth application. Find your **Client ID**, **Client Secret**, **OAuth Token URL**, and **SCIM Base URL** in **Settings → SCIM Configuration**.

Exchange these credentials for a short-lived bearer token, then send that token on every SCIM request. See [Generate an API Token](/developer-docs/api-reference/generate-token) for the token request and response, token lifetime, and reuse guidance - the flow is identical, except you use the SCIM credentials in **Settings → SCIM Configuration** instead of creating an OAuth application.

Send all SCIM requests to your **SCIM Base URL**, shown in **Settings → SCIM Configuration**. The examples below show paths relative to this base URL.

<Note>
  Every SCIM request must include an `Authorization` header carrying the bearer token you minted with your SCIM client credentials: `Authorization: Bearer YOUR_ACCESS_TOKEN`.
</Note>

## How Oleria maps roles and groups

Oleria manages user access through RBAC roles. Each role carries a predefined set of permissions that are granted to any user assigned that role.

Via SCIM, users receive roles **only through group membership**. Each group maps to exactly one role, and every member of that group inherits the role's permissions. A user who belongs to more than one group receives the combined permissions of all their groups' roles.

The `roles` attribute on a user is read-only over SCIM. It reflects the roles a user has inherited from their groups; you cannot set or change it directly on the user. To change a user's access, change their group membership or the role a group maps to. Sending `roles` in a user create, replace, or patch request returns `400 Bad Request`.

Oleria supports these predefined role values:

| Role value                    | Grants                                                                                                                                                |
| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `admin`                       | Full administrator access to all features and settings.                                                                                               |
| `operator`                    | Operator access to Adaptive Security and connected integrations.                                                                                      |
| `analyst`                     | View-only analyst access.                                                                                                                             |
| `governance-operator`         | Access to all Governance features, including access reviews, identity lifecycle, and access requests. Can view but not modify connected integrations. |
| `identity-lifecycle-operator` | Access to identity lifecycle, access bundles, and access requests. Cannot run access reviews. Can view but not modify connected integrations.         |

See [Default user roles](/administration/default-user-roles) for a description of each role.

## Provision a user with a role

Because roles are granted through groups, giving a user a role is a sequence of steps: create a group, map it to the role, create the user, then add the user to the group. Creating the group and mapping it to a role happen in a single request, and that setup is one-time per role. After that, you only create users and manage their group membership.

<Steps>
  <Step title="Create a group and map it to a role">
    Send a `POST` to `/scim/v2/Groups` with a `displayName` and the `role` the group maps to. See [Create a group](#create-a-group).

    ```json theme={null}
    {
      "displayName": "Admins",
      "role": "admin"
    }
    ```

    The response includes the group's `id` (for example, `olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b`). You use this `id` to add members.
  </Step>

  <Step title="Create the user">
    Send a `POST` to `/scim/v2/Users` with the user's `userName`, `name`, and `emails`. Do not send `roles` - the user's roles come from their groups. See [Create a user](#create-a-user).

    ```json theme={null}
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "userName": "jane@example.com",
      "name": { "formatted": "Jane Doe" },
      "emails": [{ "primary": true, "value": "jane@example.com" }]
    }
    ```

    The response includes the user's `id` (for example, `ol_8675309a-bc57-41d4-a716-446655440000`).
  </Step>

  <Step title="Add the user to the group">
    Send a `PATCH` to `/scim/v2/Groups/{id}` that adds the user to the group's `members`. The user immediately inherits the group's role. See [Update a group](#update-a-group).

    ```json theme={null}
    {
      "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
      "Operations": [
        {
          "op": "add",
          "path": "members",
          "value": [{ "value": "ol_8675309a-bc57-41d4-a716-446655440000" }]
        }
      ]
    }
    ```
  </Step>
</Steps>

<Note>
  You can combine the last two steps by including `groups` in the create request. See [Create a user](#create-a-user).
</Note>

## Users

A user's attributes follow the SCIM core schema. The full list of supported attributes is in the [SCIM core schema (RFC 7643 §4.1)](https://www.rfc-editor.org/rfc/rfc7643#section-4.1).

| Attribute    | Notes                                                                                                                                                                                  |
| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userName`   | The user's primary identifier. Must be their email address.                                                                                                                            |
| `name`       | Provide either `formatted` or the name components (for example, `givenName` and `familyName`).                                                                                         |
| `emails`     | Email addresses in SCIM format. At least one is required. Oleria associates only one email with the user: the `primary` email if one is marked, otherwise the first email in the list. |
| `active`     | Whether the user is active. Defaults to `true`. Set to `false` to deactivate the user without deleting them.                                                                           |
| `externalId` | Optional. An immutable identifier set by your provisioning client. You can set it on create; it cannot be changed afterward.                                                           |
| `groups`     | The groups the user belongs to, which determine the user's roles. Read-write: include it on create, replace, or patch to manage the user's group membership.                           |
| `roles`      | Read-only. Reflects the roles the user has inherited from their groups. Cannot be set or changed through the SCIM API.                                                                 |

### Create a user

Send a `POST` to `/scim/v2/Users`. Include `groups` to add the user to one or more groups on creation, which grants them the groups' roles. Omit `groups` to create a user with no group membership, then add them to groups later:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jane@example.com",
  "name": {
    "formatted": "Jane Doe"
  },
  "emails": [
    {
      "primary": true,
      "value": "jane@example.com"
    }
  ],
  "groups": [
    {
      "value": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
    }
  ]
}
```

Returns `201 Created`. The `roles` in the response are read-only and reflect the user's resulting membership and inherited roles:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "ol_8675309a-bc57-41d4-a716-446655440000",
  "userName": "jane@example.com",
  "name": {
    "formatted": "Jane Doe"
  },
  "emails": [
    {
      "primary": true,
      "value": "jane@example.com"
    }
  ],
  "active": true,
  "groups": [
    {
      "$ref": "https://api.YOUR_TENANT.oleria.io/scim/v2/Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
      "display": "Admins",
      "type": "direct",
      "value": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
    }
  ],
  "roles": [
    {
      "value": "admin"
    }
  ],
  "meta": {
    "resourceType": "User",
    "location": "Users/ol_8675309a-bc57-41d4-a716-446655440000"
  }
}
```

### List users

Send a `GET` to `/scim/v2/Users`. Omit `filter` to return all users, or filter on an attribute such as `userName`:

```
GET /scim/v2/Users?filter=userName eq "jane@example.com"
```

Returns `200 OK` with a list response:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "startIndex": 1,
  "itemsPerPage": 100,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "ol_8675309a-bc57-41d4-a716-446655440000",
      "userName": "jane@example.com",
      "name": {
        "formatted": "Jane Doe"
      },
      "emails": [
        {
          "primary": true,
          "value": "jane@example.com"
        }
      ],
      "active": true,
      "groups": [
        {
          "$ref": "https://api.YOUR_TENANT.oleria.io/scim/v2/Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
          "display": "Admins",
          "type": "direct",
          "value": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
        }
      ],
      "meta": {
        "resourceType": "User",
        "location": "Users/ol_8675309a-bc57-41d4-a716-446655440000"
      },
      "roles": [
        {
          "value": "admin"
        }
      ]
    }
  ]
}
```

<Note>
  The list endpoints are paginated. Use the `startIndex` (1-based) and `count` query parameters to page through results, for example `GET /scim/v2/Users?startIndex=1&count=50`. Oleria returns at most 100 results per page. Keep requesting pages until you have retrieved `totalResults` records.
</Note>

### Get a user

Send a `GET` to `/scim/v2/Users/{id}`:

```
GET /scim/v2/Users/ol_8675309a-bc57-41d4-a716-446655440000
```

Returns `200 OK`:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "ol_8675309a-bc57-41d4-a716-446655440000",
  "userName": "jane@example.com",
  "name": {
    "formatted": "Jane Doe"
  },
  "emails": [
    {
      "primary": true,
      "value": "jane@example.com"
    }
  ],
  "active": true,
  "groups": [
    {
      "$ref": "https://api.YOUR_TENANT.oleria.io/scim/v2/Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
      "display": "Admins",
      "type": "direct",
      "value": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
    }
  ],
  "meta": {
    "resourceType": "User",
    "location": "Users/ol_8675309a-bc57-41d4-a716-446655440000"
  },
  "roles": [
    {
      "value": "admin"
    }
  ]
}
```

### Replace a user

Send a `PUT` to `/scim/v2/Users/{id}` to replace a user's attributes with those in the request. This example moves the user to a different group, which changes their inherited role:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jane@example.com",
  "name": {
    "formatted": "Jane Doe"
  },
  "emails": [
    {
      "primary": true,
      "value": "jane@example.com"
    }
  ],
  "groups": [
    {
      "value": "olg_9f8e7d6c-5b4a-4c3d-9e2f-1a0b2c3d4e5f"
    }
  ]
}
```

<Note>
  A `PUT` replaces the user's writable attributes with the values you send, so include every attribute you want to keep. Two exceptions: `roles` is read-only, so sending it returns `400 Bad Request`; and omitting `groups` leaves the user's current group membership unchanged rather than clearing it. To remove the user from all groups, send an empty `groups` array.
</Note>

Returns `200 OK`:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "ol_8675309a-bc57-41d4-a716-446655440000",
  "userName": "jane@example.com",
  "name": {
    "formatted": "Jane Doe"
  },
  "emails": [
    {
      "primary": true,
      "value": "jane@example.com"
    }
  ],
  "active": true,
  "groups": [
    {
      "$ref": "https://api.YOUR_TENANT.oleria.io/scim/v2/Groups/olg_9f8e7d6c-5b4a-4c3d-9e2f-1a0b2c3d4e5f",
      "display": "Operators",
      "type": "direct",
      "value": "olg_9f8e7d6c-5b4a-4c3d-9e2f-1a0b2c3d4e5f"
    }
  ],
  "meta": {
    "resourceType": "User",
    "location": "Users/ol_8675309a-bc57-41d4-a716-446655440000"
  },
  "roles": [
    {
      "value": "operator"
    }
  ]
}
```

### Update a user

Send a `PATCH` to `/scim/v2/Users/{id}` to change specific attributes without replacing the whole user. The request body is a SCIM `PatchOp` with one or more operations.

Oleria supports these operations on users:

| Attribute (`path`) | Operations                 | Notes                                                                                                            |
| :----------------- | :------------------------- | :--------------------------------------------------------------------------------------------------------------- |
| `groups`           | `add`, `remove`, `replace` | Manage the user's group membership, which determines their roles.                                                |
| `active`           | `replace`                  | Set to `false` to deactivate the user or `true` to reactivate them.                                              |
| `name`             | `replace`                  | Replace the user's name. Provide `formatted` or the name components (for example, `givenName` and `familyName`). |

Any other `path`, or an unsupported operation on a supported `path`, returns `400 Bad Request`. The `roles` attribute is read-only and cannot be patched.

Add the user to a group:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "groups",
      "value": [
        {
          "value": "olg_9f8e7d6c-5b4a-4c3d-9e2f-1a0b2c3d4e5f"
        }
      ]
    }
  ]
}
```

Remove the user from a group:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "groups",
      "value": [
        {
          "value": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
        }
      ]
    }
  ]
}
```

Replace the user's entire group membership with a new set:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "groups",
      "value": [
        {
          "value": "olg_9f8e7d6c-5b4a-4c3d-9e2f-1a0b2c3d4e5f"
        }
      ]
    }
  ]
}
```

To remove the user from all groups at once, send a `remove` operation on `groups` with no `value`:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "groups"
    }
  ]
}
```

Deactivate a user:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": false
    }
  ]
}
```

Change a user's name:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "name",
      "value": {
        "formatted": "Jane M. Doe"
      }
    }
  ]
}
```

Each request returns `200 OK` with the updated user resource, or `204 No Content` if the operations produced no change.

### Delete a user

Send a `DELETE` to `/scim/v2/Users/{id}`:

```
DELETE /scim/v2/Users/ol_8675309a-bc57-41d4-a716-446655440000
```

Returns `204 No Content` with no response body.

## Groups

A group's attributes follow the SCIM core schema. The full list of supported attributes is in the [SCIM core schema (RFC 7643 §4.2)](https://www.rfc-editor.org/rfc/rfc7643#section-4.2). In addition to the standard `displayName` and `members`, Oleria adds a `role` attribute that records which role the group maps to. All members of the group inherit that role.

### Create a group

Send a `POST` to `/scim/v2/Groups`:

```json theme={null}
{
  "displayName": "Admins",
  "members": [
    {
      "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
    }
  ],
  "role": "admin"
}
```

Returns `201 Created`:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
  "displayName": "Admins",
  "members": [
    {
      "$ref": "urn:ietf:params:scim:schemas:core:2.0:User",
      "display": "user@example.com",
      "type": "User",
      "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "location": "Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
  },
  "role": "admin"
}
```

### List groups

Send a `GET` to `/scim/v2/Groups`:

```
GET /scim/v2/Groups
```

Returns `200 OK` with a list response:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "startIndex": 1,
  "itemsPerPage": 100,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
      "id": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
      "displayName": "Admins",
      "members": [
        {
          "$ref": "urn:ietf:params:scim:schemas:core:2.0:User",
          "display": "user@example.com",
          "type": "User",
          "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
        }
      ],
      "meta": {
        "resourceType": "Group",
        "location": "Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
      },
      "role": "admin"
    }
  ]
}
```

<Note>
  As with [List users](#list-users), the response is paginated with `startIndex` and `count`, returning at most 100 results per page.
</Note>

### Get a group

Send a `GET` to `/scim/v2/Groups/{id}`:

```
GET /scim/v2/Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b
```

Returns `200 OK`:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
  "displayName": "Admins",
  "members": [
    {
      "$ref": "urn:ietf:params:scim:schemas:core:2.0:User",
      "display": "user@example.com",
      "type": "User",
      "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "location": "Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
  },
  "role": "admin"
}
```

### Replace a group

Send a `PUT` to `/scim/v2/Groups/{id}` to replace all of a group's attributes with those in the request. As with a create request, all attributes must be included. This example changes the group's `role`:

```json theme={null}
{
  "displayName": "Admins",
  "members": [
    {
      "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
    }
  ],
  "role": "operator"
}
```

Returns `200 OK`:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b",
  "displayName": "Admins",
  "members": [
    {
      "$ref": "urn:ietf:params:scim:schemas:core:2.0:User",
      "display": "user@example.com",
      "type": "User",
      "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "location": "Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b"
  },
  "role": "operator"
}
```

### Update a group

Send a `PATCH` to `/scim/v2/Groups/{id}` to change specific attributes without replacing the whole group. The request body is a SCIM `PatchOp` with one or more operations.

Oleria supports these operations on groups:

| Attribute (`path`) | Operations                 | Notes                                                                |
| :----------------- | :------------------------- | :------------------------------------------------------------------- |
| `members`          | `add`, `remove`, `replace` | Manage the group's membership. `replace` sets the full member list.  |
| `role`             | `replace`                  | Change the role the group maps to. All members inherit the new role. |
| `displayName`      | `replace`                  | Rename the group.                                                    |

Any other `path`, or an unsupported operation on a supported `path`, returns `400 Bad Request`.

Change the group's `role`:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "role",
      "value": "operator"
    }
  ]
}
```

Rename the group:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "Platform Admins"
    }
  ]
}
```

Add a member to the group:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "ol_4b18b2d4-0751-4fea-afd7-27ae7c1785c0"
        }
      ]
    }
  ]
}
```

Remove a member from the group:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "members",
      "value": [
        {
          "value": "ol_fb81d732-4ac0-4d0c-af20-478bbc9b3cb5"
        }
      ]
    }
  ]
}
```

Each request returns `200 OK` with the updated group resource, or `204 No Content` if the operations produced no change.

### Delete a group

Send a `DELETE` to `/scim/v2/Groups/{id}`:

```
DELETE /scim/v2/Groups/olg_46a6d854-46b0-4f1f-bb67-34b852c1ad6b
```

Returns `204 No Content` with no response body.

## Service provider configuration endpoints

Oleria supports the standard SCIM discovery endpoints so clients can inspect the service provider's capabilities. See the [SCIM protocol, service provider configuration (RFC 7644 §4)](https://www.rfc-editor.org/rfc/rfc7644#section-4) for details.

| Endpoint                             | Purpose                                                        |
| :----------------------------------- | :------------------------------------------------------------- |
| `GET /scim/v2/ResourceTypes`         | Discover the resource types Oleria supports: Users and Groups. |
| `GET /scim/v2/Schemas`               | Retrieve the resource schemas Oleria supports.                 |
| `GET /scim/v2/ServiceProviderConfig` | Describe the SCIM features available on the service provider.  |

## SCIM specification reference

* [SCIM definitions, overview, and concepts (RFC 7642)](https://www.rfc-editor.org/rfc/rfc7642)
* [SCIM core schema (RFC 7643)](https://www.rfc-editor.org/rfc/rfc7643)
* [SCIM protocol (RFC 7644)](https://www.rfc-editor.org/rfc/rfc7644)

## Contact us

For questions about SCIM provisioning, contact us at [support@oleria.com](mailto:support@oleria.com).