Set up SCIM with another SCIM 2.0 client - Living Security Platform

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. If the card says SCIM is set up and managed in the setup wizard, use SCIM Provisioning.

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 and RFC 7644.

What you need

A Living Security admin with permission to manage SSO and SCIM settings.
An administrator of your IdP, or a setup link 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.

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

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).
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. Endpoints, filters, pagination, PATCH, Bulk and limits are in the API reference.

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.

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 with one person first. In short:

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.
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.
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.
To see the exact request your IdP sent, look at Newest user on the Attributes tab, or search the SCIM events for the person’s email.
Ask the test person to sign in. First sign-in by a SCIM user shows Done.
Send one group. First group received shows Done.
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	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	A required attribute is missing. Map `userName` for users and `displayName` for groups.
LS-SCIM-1104	A value has the wrong type. Correct the mapping, for example `active` must be true or false.
LS-SCIM-1107	No usable email. Map the person’s email to `emails[type eq "work"].value`.
LS-SCIM-1108	More than one primary email. Mark exactly one email as primary.
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	Unknown filter attribute. Filter on an attribute that `/Schemas` lists.
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	Rate limited. No action: your IdP retries after the `Retry-After` time.
LS-SCIM-1602	Changes paused. No action: your IdP retries.
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. Every code is in the SCIM error reference. For a support request, select Copy diagnostics on the troubleshooting page. It has no names, email addresses or tokens.

Settings

What you need

Base URL

Authentication

Discovery

What Living Security expects

Try it with curl

Test your setup

Troubleshoot

Related