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

# SCIM provisioning

> Let Okta, Entra ID or any SCIM 2.0 client create, update and deactivate Quotable members, and map identity provider groups to roles.

> [!NOTE]
>
> **Plans:** Growth and Enterprise · **In the app:** Settings → Security → Single sign-on → Provisioning (SCIM 2.0)

SCIM 2.0 lets your identity provider (IdP) manage your Quotable team for you. When someone joins, changes name or leaves in your IdP, the change reaches Quotable within the same request: no manual invites, and no forgotten accounts after offboarding.

> [!NOTE]
>
> Only **owners** manage SCIM, from **Settings → Security → Single sign-on → Provisioning (SCIM 2.0)**, and every change asks for [recent re-authentication](https://docs.usequotable.com/workspace/security.md#recent-re-authentication).

## Before you start

SCIM only provisions people whose email is in a domain your workspace has **verified** for single sign-on. Set up and verify an SSO connection first. See [Single sign-on](https://docs.usequotable.com/workspace/sso.md).

## Connection details

| Setting | Value |
| - | - |
| Base URL | `https://app.usequotable.com/api/scim/v2` |
| Authentication | `Authorization: Bearer scim_…` |
| Unique identifier | `userName`, set to the member's email address |
| Content type | `application/scim+json` (`application/json` is also accepted) |

## Issue a token

**1. Issue**

In **Settings → Security → Single sign-on → Provisioning (SCIM 2.0)**, choose **Issue token**.

**2. Copy it now**

The token starts with `scim_` and is shown **once**, so copy it now.

**3. Paste it into your IdP**

Use it as the bearer token in your IdP's provisioning settings.

The token list shows each token's prefix, creation date and last use. A workspace can hold up to **three active tokens**, so you can rotate without downtime: issue a new token, update your IdP, then **Revoke** the old one. Revocation is immediate.

## Set up Okta

**1. Enable SCIM**

In your Quotable app in Okta, enable **SCIM provisioning**, then open the **Provisioning** tab.

**2. Connect**

Set **SCIM connector base URL** to `https://app.usequotable.com/api/scim/v2`, **Unique identifier field for users** to `userName`, and **Authentication Mode** to **HTTP Header** with your token. Test the connector configuration.

**3. Choose what Okta may do**

Under **To App**, enable **Create Users**, **Update User Attributes** and **Deactivate Users**.

**4. Push groups**

Assign people to the app, then use **Push Groups** for the groups you want to map to roles.

## Set up Microsoft Entra ID

**1. Open provisioning**

In **Enterprise applications**, open your Quotable app, then **Provisioning**, and set the mode to **Automatic**.

**2. Connect**

Set **Tenant URL** to `https://app.usequotable.com/api/scim/v2` and **Secret Token** to your token. Choose **Test Connection**.

**3. Check mappings**

Make sure `userName` maps to the user's email address (usually `userPrincipalName` or `mail`).

**4. Assign and start**

Assign the users and groups in scope, then start provisioning.

## Map groups to roles

Your IdP never sends roles. Instead, an owner maps IdP **groups** to Quotable roles in **Settings → Security → Single sign-on → Group → role map**.

* Groups appear in the map once your IdP pushes them. You can also **Map group** by display name ahead of time; the mapping is picked up when the group arrives.
* A group can map to **viewer**, **editor**, **integration admin** or **billing admin**. **Owner** is never assigned by provisioning.
* A member's role is the **highest** role among their groups, in this order: billing admin, integration admin, editor, viewer.
* A member in no mapped group is a **viewer**.
* Changing a mapping updates every affected member's role immediately and tells you how many changed.
* Members you invited by hand who are not in any SCIM group keep the role you gave them.

> [!NOTE]
>
> Roles decide what someone can do. Brand access is still granted by an owner in **Settings → Members**. See [Team and roles](https://docs.usequotable.com/workspace/team-and-roles.md).

## What each operation does

| IdP action | Effect in Quotable |
| - | - |
| **Create user** | Adds the person as a **viewer**, then applies their group roles. If they already have a Quotable login (in another workspace or invited here by hand), that login is linked, not duplicated. |
| **Update user** | Updates name, `userName` and `externalId`. Setting `active: true` on a deactivated member restores them. |
| **Deactivate** (`active: false`) | Turns off the member's access immediately and ends their sessions in this workspace. Their content and brand grants stay, so reactivating restores them as they were. API keys and webhooks they created are revoked or disabled. |
| **Delete user** | Deactivates, then removes them from the team. Owners cannot be deleted by SCIM; demote them in **Settings → Members** first. |
| **Group changes** | Adds or removes members and renames groups, then recomputes the roles of everyone affected. |

Sessions the person holds in other workspaces are not affected.

## Supported endpoints

| Resource | Methods |
| - | - |
| `/Users` | `GET` (list and filter), `POST` |
| `/Users/{id}` | `GET`, `PUT`, `PATCH`, `DELETE` |
| `/Groups` | `GET` (list and filter), `POST` |
| `/Groups/{id}` | `GET`, `PUT`, `PATCH`, `DELETE` |
| `/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas` | `GET` |

### Filtering and pagination

Filters take a single `eq` clause:

| Resource | Filterable attributes |
| - | - |
| Users | `userName`, `externalId`, `emails.value`, `id` |
| Groups | `displayName`, `externalId`, `id` |

```http theme={"system"}
GET /api/scim/v2/Users?filter=userName eq "jane@acme.com"
Authorization: Bearer scim_…
```

Pagination uses `startIndex` (1-based) and `count`. The default page size is 100 and the maximum is 200. On `/Groups`, `excludedAttributes=members` is honored.

### PATCH

`PATCH` accepts `add`, `replace` and `remove` operations, in any letter case.

* **Users:** `active`, `userName`, `externalId`, `name.*` and `displayName`. Other standard attributes are accepted and ignored.
* **Groups:** `members` (including `members[value eq "…"]`), `displayName` and `externalId`.

### Example user

```json theme={"system"}
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "6f1c2e4a-…",
  "userName": "jane@acme.com",
  "name": { "givenName": "Jane", "familyName": "Doe", "formatted": "Jane Doe" },
  "displayName": "Jane Doe",
  "emails": [{ "value": "jane@acme.com", "primary": true, "type": "work" }],
  "active": true,
  "groups": [{ "value": "a1b2…", "display": "Quotable Editors", "$ref": "…/Groups/a1b2…" }],
  "meta": { "resourceType": "User", "created": "…", "lastModified": "…", "location": "…/Users/6f1c2e4a-…" }
}
```

## Not supported

* Bulk operations, sorting, ETags and `/.search`.
* Filters other than a single `eq` clause.
* Password changes.
* Changing a member's email address. A new address sent by the IdP is ignored; the person changes it themselves from their profile.
* Users outside your verified SSO domains.

## Limits and errors

Requests are limited to **600 per 5 minutes** per workspace. Request bodies are limited to 256 KB. Errors follow the SCIM error format:

```json theme={"system"}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "A user with that userName or externalId already exists."
}
```

| Status | `scimType` | When |
| - | - | - |
| `400` | `invalidFilter` | The filter is not a single `eq` clause on a supported attribute. |
| `400` | `invalidValue` | A required value is missing (`userName`, `displayName`), or the address is not in a verified SSO domain of this workspace. |
| `400` | `invalidSyntax` | The body is not valid JSON or a `PATCH` operation is malformed. |
| `400` | `mutability` | You tried to delete an owner. |
| `401` | | The token is missing, unknown or revoked. |
| `403` | | The workspace's plan no longer includes SCIM provisioning. |
| `404` | | The user or group does not exist in this workspace. |
| `409` | `uniqueness` | A user with that `userName` or `externalId`, or a group with that `displayName` or `externalId`, already exists. |
| `429` | `tooMany` | Rate limit reached. Retry after the `Retry-After` header. |
| `500` | | Provisioning failed and nothing was applied. Retry. |

Creating a user who already exists in the workspace but is not yet managed by SCIM links them and returns `201`, so an IdP retry never creates duplicates.

## Audit trail

Every SCIM change is recorded in the [audit log](https://docs.usequotable.com/workspace/audit-log.md): tokens issued and revoked, users provisioned, updated, deactivated and removed, group changes and group-to-role mappings.

## Next steps

> [card] [Single sign-on](https://docs.usequotable.com/workspace/sso.md)
>
> Required before SCIM can provision.

> [card] [Team and roles](https://docs.usequotable.com/workspace/team-and-roles.md)
>
> What each mapped role can do.

> [card] [Audit log](https://docs.usequotable.com/workspace/audit-log.md)
>
> Review what your IdP changed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.