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

# Set up SCIM with another SCIM 2.0 client

> Connect any SCIM 2.0 identity provider or script to Living Security SCIM: base URL, authentication, discovery, attribute expectations, test steps and troubleshooting.

> [!NOTE]
>
> **Which SCIM setup applies to you?** These pages describe **Living Security SCIM**. Open the SCIM card in your settings. If the card shows **Set up SCIM**, or its **Mode** row says **Native SCIM**, these pages apply. If **Mode** says **Current SCIM**, your organization still uses the earlier SCIM setup. An admin can move it: see [Move from the earlier SCIM setup](https://docs.livingsecurity.com/features/settings/scim/connection.md#move-from-the-earlier-scim-setup). If the card says SCIM is set up and managed in the setup wizard, use [SCIM Provisioning](https://docs.livingsecurity.com/features/settings/scim.md).

Use this guide for an identity provider (IdP) that has no guide of its own, or for your own SCIM 2.0 client. Living Security SCIM follows the SCIM 2.0 standard: [RFC 7643](https://www.rfc-editor.org/rfc/rfc7643) and [RFC 7644](https://www.rfc-editor.org/rfc/rfc7644).

## What you need

* A Living Security admin with permission to manage SSO and SCIM settings.
* An administrator of your IdP, or a [setup link](https://docs.livingsecurity.com/features/settings/scim/connection.md#send-a-setup-link-to-your-it-administrator) you send to one.
* SSO is not required. If you use SSO, the SCIM `userName` must be the same value your SSO sends as the NameID: the person's email address. See [SSO and sub-organizations](https://docs.livingsecurity.com/features/settings/scim/sso-and-sub-organizations.md).

## Base URL

Copy the base URL from the SCIM card. It belongs to your organization's data residency region, for example `https://api.us-east-1.livingsecurity.ai/scim/v2`. See [Regional base URLs](https://docs.livingsecurity.com/features/settings/scim/overview.md#regional-base-urls).

Send requests over HTTPS with `Content-Type: application/scim+json` or `application/json`.

## Authentication

| Method | What your client sends | How to get it |
| - | - | - |
| Bearer token | `Authorization: Bearer lsscim_...` | **Set up SCIM** on the SCIM card. |
| HTTP Basic | `Authorization: Basic <base64 of username:password>` | Contact Living Security support. |
| OAuth 2.0 client credentials | `Authorization: Bearer <access token>` with the `scim:provision` scope | Contact Living Security support. |

Use the bearer token when your client supports it. See [API reference: Authentication](https://docs.livingsecurity.com/features/settings/scim/api-reference.md#authentication).

## Discovery

Every endpoint needs authentication, discovery included.

* `GET /ServiceProviderConfig`: PATCH, Bulk (1,000 operations, 1 MiB), filters (1,000 results), sorting, ETags and pagination by index and cursor. `changePassword` is not supported.
* `GET /ResourceTypes`: `User`, with the Enterprise and Living Security extensions, and `Group`.
* `GET /Schemas`: the core, Enterprise and Living Security schemas, and each custom extension your client has sent.

## What Living Security expects

* **`userName`** is required and unique, without regard to case. Use the person's email address, the same value your SSO sends as the NameID.
* **One usable email** for every active user. Send one email marked `"primary": true`.
* **`active`** follows the person's state in your directory. Send `active: false` to deactivate.
* **Matching.** Before a create, search with `filter=userName eq "..."`. A create with a `userName` that exists returns `409` ([LS-SCIM-1201](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1201)).
* **Extensions.** Send Enterprise and Living Security attributes inside their schema URN, and use the full URN in PATCH paths.
* **`PUT` replaces the whole user.** An attribute that is not in a `PUT` is cleared.
* **Groups.** Send `displayName` and `members` with user `id` values. An unknown member `id` returns `400`.
* **Retries.** On `429` or `503`, wait for the `Retry-After` time, then retry.

Every attribute and what it updates on the person is in the [SCIM attribute reference](https://docs.livingsecurity.com/features/settings/scim/attributes.md). Endpoints, filters, pagination, PATCH, Bulk and limits are in the [API reference](https://docs.livingsecurity.com/features/settings/scim/api-reference.md).

## Try it with curl

Replace the base URL and the token with your own. Keep the token out of scripts and shell history in real use.

```bash theme={null}
BASE="https://api.us-east-1.livingsecurity.ai/scim/v2"

curl -s "$BASE/ServiceProviderConfig" \
  -H "Authorization: Bearer $SCIM_TOKEN"

curl -s -X POST "$BASE/Users" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "test.person@example.com",
    "name": { "givenName": "Test", "familyName": "Person" },
    "emails": [{ "value": "test.person@example.com", "type": "work", "primary": true }],
    "active": true
  }'
```

The create returns `201` with the user's `id`. Every response has an `X-Request-Id` header. To try a body without saving it, use **Troubleshoot SCIM → Validate → Test a payload**.

## Test your setup

Follow [Test your SCIM setup](https://docs.livingsecurity.com/features/settings/scim/testing.md) with one person first. In short:

1. Run your IdP's connection test, or send `GET /ServiceProviderConfig`. On the Living Security **Checklist** tab, **First request received** and **Connection test passed** show **Done**.
2. Assign one test person in your IdP, or create one user. **First user received**, then **First user ready to sign in**, show **Done** within a few minutes.
3. Open the **Attributes** tab. Fix each item under **What to fix**, and check that **Attributes received** has the attributes you mapped. Compare with the [SCIM attribute reference](https://docs.livingsecurity.com/features/settings/scim/attributes.md).
4. To see the exact request your IdP sent, look at **Newest user** on the **Attributes** tab, or search the [SCIM events](https://docs.livingsecurity.com/features/settings/scim.md#review-received-scim-requests) for the person's email.
5. Ask the test person to sign in. **First sign-in by a SCIM user** shows **Done**.
6. Send one group. **First group received** shows **Done**.
7. Send `active: false` for the test person. The person shows as deactivated in **Workforce → People**.

When every step shows **Done** or **Not used** and the **Health** tab shows **No warnings**, widen the scope in your IdP.

## Troubleshoot

Each failed request has an `LS-SCIM` code in the error `detail`. your IdP shows it in its provisioning logs. Open **Troubleshoot SCIM → Health** in Living Security for failed requests, held accounts and token expiry.

| Code | Meaning and fix |
| - | - |
| [LS-SCIM-1001](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1001) | Authentication failed. Copy the SCIM base URL and a current token from the SCIM card into your IdP again. A token sent to another region's base URL also fails. |
| [LS-SCIM-1103](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1103) | A required attribute is missing. Map `userName` for users and `displayName` for groups. |
| [LS-SCIM-1104](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1104) | A value has the wrong type. Correct the mapping, for example `active` must be true or false. |
| [LS-SCIM-1107](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1107) | No usable email. Map the person's email to `emails[type eq "work"].value`. |
| [LS-SCIM-1108](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1108) | More than one primary email. Mark exactly one email as primary. |
| [LS-SCIM-1201](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1201) | The `userName` is already in use. Two your IdP users map to the same `userName`, or your IdP did not match an existing user. |
| [LS-SCIM-1305](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1305) | Unknown filter attribute. Filter on an attribute that `/Schemas` lists. |
| [LS-SCIM-1401](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1401) | Invalid PATCH path. Use the full URN for extension attributes, for example `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department`. |
| [LS-SCIM-1601](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1601) | Rate limited. No action: your IdP retries after the `Retry-After` time. |
| [LS-SCIM-1602](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1602) | Changes paused. No action: your IdP retries. |
| [LS-SCIM-1604](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1604) | Internal error. Retry. If it continues, contact Living Security support with the output of **Copy diagnostics**. |

Some changes succeed in your IdP but are held in Living Security, for example a change that would remove your last owner. The SCIM card shows **Held accounts**. See [Held changes](https://docs.livingsecurity.com/features/settings/scim/user-lifecycle.md#held-changes).

Every code is in the [SCIM error reference](https://docs.livingsecurity.com/features/settings/scim/errors.md). For a support request, select **Copy diagnostics** on the troubleshooting page. It has no names, email addresses or tokens.

## Related

* [SCIM attribute reference](https://docs.livingsecurity.com/features/settings/scim/attributes.md)
* [Test your SCIM setup](https://docs.livingsecurity.com/features/settings/scim/testing.md)
* [SCIM error reference](https://docs.livingsecurity.com/features/settings/scim/errors.md)
* [API reference and limits](https://docs.livingsecurity.com/features/settings/scim/api-reference.md)


## Related topics

- [Set up a SCIM connection](https://docs.livingsecurity.com/features/settings/scim/connection.md)
- [Set up SCIM with SailPoint](https://docs.livingsecurity.com/features/settings/scim-sailpoint.md)
- [Set up SCIM with Okta](https://docs.livingsecurity.com/features/settings/scim-okta.md)


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