---
title: "SCIM provisioning"
description: "Let your identity provider create, update, suspend and remove your organization's people and groups over SCIM 2.0."
---

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

# SCIM provisioning

With SCIM provisioning, your identity provider (such as Okta or Microsoft Entra ID) manages your organization's people and groups over SCIM 2.0. It creates and updates users, suspends and removes them, and pushes groups and their members. You attach policies to the provisioned groups in EZGH Cloud.

SCIM is on while your organization has at least one SCIM token.

## Before you start

- SCIM provisions only people whose email address is in a domain, or a subdomain of a domain, verified on one of your organization's SSO providers. Verify the domain in the console under **IAM** > **Directory** first. See [Directory](/iam/directory#verify-a-domain).
- Creating and deleting SCIM tokens needs `scim.tokens.create` and `scim.tokens.delete`, which are in `IAMFullAccess`. A SCIM token provisions and suspends people, so treat these as administrator permissions.

## Turn SCIM on

Create a SCIM token. The first token turns SCIM on.

### Console

1. Open **IAM** > **SCIM** and select **Create token**.
2. Enter a **Name**, such as the identity provider's name.
3. Review what turning SCIM on changes, then select **Create token and turn on SCIM**.
4. Copy the token and the **Base URL**. The token isn't shown again.
### CLI

```sh
ezgh iam scim tokens create okta
ezgh iam scim status
```

The token is printed once, on standard output. `ezgh iam scim status` shows the base URL.
### API

```sh
curl https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/scim/tokens \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "okta"}'
```

The response's `token` is shown once. See [CreateScimToken](/orgs-api/scim/CreateScimToken/).

| Token property | Value |
| --- | --- |
| Format | `ezgh_scim_` followed by 43 letters and digits |
| Expiry | Never |
| Rate limit | 1,200 requests per minute per token. Over it, `429` with `Retry-After`. |
| Accepted | Only by the SCIM endpoint. It isn't an API key. |

## Configure your identity provider

In your identity provider's SCIM 2.0 app, set:

| Setting | Value |
| --- | --- |
| Base URL | `https://orgs.ezghcloud.com/scim/v2` |
| Authentication | HTTP header, bearer token: your SCIM token |
| Unique identifier for users | `userName`, the email address people sign in with |

Turn on creating, updating and deactivating users, and push the groups you want to manage. The **Setup** tab of **IAM** > **SCIM** has steps and attribute mappings for Okta and Microsoft Entra ID.

Then attach policies to the provisioned groups. See [Attach policies to a group](/iam/groups#attach-policies-to-a-group).

## What SCIM changes

While SCIM is on:

- Your identity provider adds, updates, suspends and removes people in your verified domains.
- Signing in through your SSO provider no longer adds people, and no longer syncs SSO group mappings. Someone your identity provider hasn't provisioned can't sign in through SSO.
- You can't remove provisioned users, or rename, delete or change the members of provisioned groups, in EZGH Cloud. These requests return `409` with `managed_by_scim`.
- You can't invite email addresses in your verified domains. You can still invite people from other domains.
- You still manage policies for provisioned users and groups, provisioned users' membership in groups you created, your own groups, bots and API keys.

Provisioned users and groups show **Managed by SCIM** in the console.

## Users

A provisioned user's email address is their primary email, else their `work` email, else their first email, else `userName`. It must be in a verified domain.

- If an account with that email address exists and isn't in another organization, it's linked and joins your organization. A person in another organization is refused with `409`.
- A provisioned user's email address counts as verified.
- `active: false` suspends the user: they can't sign in by any method, they're signed out everywhere, and their API keys are revoked. They stay in the organization with their groups and policies. `active: true` restores their sign-in; revoked API keys don't come back.
- `DELETE` deprovisions the user: they're suspended, then removed from the organization with their group memberships, policies and API keys.
- The root user can't be suspended or deleted through SCIM (`400`, `mutability`). Make someone else root first.

Stored attributes: `userName` (unique in the organization, compared without case), `externalId`, `name`, `displayName`, `emails` (up to 10), `active`, and the enterprise extension's `department` and `manager`. `groups` is read-only. Other attributes are accepted and ignored.

## Groups

A provisioned group is an ordinary group whose name (`displayName`) and members come from your identity provider. Members are users only; groups can't contain groups. `displayName` is unique among provisioned groups, compared without case. Deleting a group through SCIM removes its memberships and policy attachments.

## Supported operations

| Endpoint | Methods |
| --- | --- |
| `/ServiceProviderConfig` | `GET` |
| `/ResourceTypes`, `/Schemas` | `GET` |
| `/Users` | `GET`, `POST` |
| `/Users/{id}` | `GET`, `PUT`, `PATCH`, `DELETE` |
| `/Groups` | `GET`, `POST` |
| `/Groups/{id}` | `GET`, `PUT`, `PATCH`, `DELETE` |

- `/Users` and `/Groups` list only what SCIM provisioned. Lists take `startIndex`, `count` (default 100, at most 200), `attributes` and `excludedAttributes`.
- `filter` takes `eq` comparisons joined with `and`. Users can be filtered by `userName`, `externalId`, `id`, `displayName`, `active` and `emails` (`emails.value`, `emails[type eq "work"].value`). Groups can be filtered by `displayName`, `externalId`, `id` and `members` (`members.value`, `members[value eq "…"]`).
- `PATCH` supports `add`, `replace` and `remove`, in the forms Okta and Microsoft Entra ID send. It applies all operations or none.
- Not supported: bulk operations, `/Me`, `POST /.search`, sorting, ETags, password changes and nested groups.

Errors use the SCIM error format:

| Status | `scimType` | When |
| --- | --- | --- |
| `400` | `invalidSyntax` | The body isn't valid JSON, or a `PATCH` operation is malformed |
| `400` | `invalidFilter` | The filter isn't supported |
| `400` | `invalidValue` | A required attribute is missing, a value is invalid, a member is unknown, or the email domain isn't verified |
| `400` | `mutability` | Suspending or deleting the root user |
| `400` | `noTarget` | `remove` without a path |
| `401` | | No SCIM token, or one that was deleted |
| `404` | | No such user or group in your organization |
| `409` | `uniqueness` | The `userName`, group `displayName` or email address is taken, or the person belongs to another organization |
| `429` | | Over the token's rate limit |
| `503` | | Temporarily unavailable. Retry after `Retry-After` seconds. |

Every change your identity provider makes is recorded in Trails.

## Rotate a token

Tokens don't expire. To rotate one, create a second token, switch your identity provider to it, then delete the first. The token list shows when each token was **Last used**.

## Turn SCIM off

Deleting your organization's last SCIM token turns SCIM off. In the console, select **Delete** next to the token on **IAM** > **SCIM**, then **Delete and turn off SCIM**. With the CLI, run `ezgh iam scim tokens delete <token>`. See [DeleteScimToken](/orgs-api/scim/DeleteScimToken/).

When SCIM turns off:

- Your identity provider can no longer change anything.
- Provisioned groups become ordinary groups, and active provisioned users ordinary members, that you manage in EZGH Cloud.
- Suspended users stay suspended until you reactivate them: open the user's page and select **Reactivate** (`users.reactivate`), or call [ReactivateUser](/orgs-api/userAccess/ReactivateUser/).
- Signing in through your SSO provider adds people again and syncs SSO group mappings on every sign-in.

Source: https://docs.ezghcloud.com/iam/scim/index.mdx