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

# SCIM attribute reference

> Every core, Enterprise and Living Security SCIM attribute: type, mutability, case rules, whether it is required, what it updates on the person, and how to map it from your identity provider.

> [!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).

This page lists every SCIM attribute Living Security SCIM declares, and what each one changes on the person in **Workforce → People**. Use it when you map attributes in your identity provider (IdP).

## The attributes that matter most

Map these first. The **Attributes** tab on **Troubleshoot SCIM** checks them for every person your IdP sends.

| Attribute | Need | Why |
| - | - | - |
| `userName` | Required | The person's login name. Use the person's email address, the same value your SSO sends as the NameID. |
| `emails[type eq "work"].value` | Required for an active person | Living Security sends training and notices to this address. An active person with no usable email is refused. |
| `active` | Recommended | Without it, a removal in your IdP may not deactivate the person. |
| `name.givenName`, `name.familyName` | Recommended | First and last name on the person. |
| `title` | Recommended | Job title. |
| Enterprise `department` | Recommended | Department, used in cohorts and reports. |
| Enterprise `manager` | Recommended | The person's manager. |
| Enterprise `employeeNumber` | Optional | Employee number. |

### Email

Living Security picks one email for the person, in this order:

1. The email marked `"primary": true`.
2. The first email with `type` `work`.
3. The first email.
4. The `userName`, when it is an email address.

Send one email and mark it primary. More than one primary email is refused with [LS-SCIM-1108](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1108). An active person with no usable email is refused with [LS-SCIM-1107](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1107). See [Email changes](https://docs.livingsecurity.com/features/settings/scim/user-lifecycle.md#email-changes).

## How to read the tables

* **Type** is the SCIM data type. A `complex` attribute has the sub-attributes listed after it, as `attribute.subAttribute`.
* **Required** means a create or replace without it is refused.
* **Mutability:** **Read and write** can be sent and changed. **Read only** is set by Living Security. A read-only value inside a `POST`, `PUT` or `PATCH` body is ignored, but a PATCH operation whose `path` names a read-only attribute is refused with [LS-SCIM-1405](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1405). **Set once** can be sent on create but not changed. **Write only** is accepted and never returned. `password` is accepted and discarded, never stored.
* **Case-sensitive** applies to text. When it says **No**, `Alex@Example.com` and `alex@example.com` are the same value in filters and uniqueness checks.
* **Rules:** **Unique in your organization** means two resources of the same type cannot share the value. **Suggested values** are the values SCIM defines. Other text is also accepted.
* **Updates on the person** names what the attribute changes on the person in Living Security. **Not used** means the attribute changes nothing on the person. Living Security stores a writable value and returns it to your IdP.

Every writable attribute your IdP sends is stored and returned, including the ones marked **Not used**. Read-only values and `password` are not stored. An admin's manual edit of a person's value wins over later SCIM updates until the admin resets it. See [Update](https://docs.livingsecurity.com/features/settings/scim/user-lifecycle.md#update).

## Attribute tables

### Core user

Schema URN: `urn:ietf:params:scim:schemas:core:2.0:User`

| Attribute | Type | Required | Mutability | Case-sensitive | Rules | Updates on the person |
| - | - | - | - | - | - | - |
| `id` | `string` | No | Read only | Yes | Unique in your organization | Not used |
| `externalId` | `string` | No | Read and write | Yes | | Stored link to the IdP record |
| `meta` | `complex` | No | Read only | | | |
| `meta.resourceType` | `string` | No | Read only | Yes | | Not used |
| `meta.created` | `dateTime` | No | Read only | | | Not used |
| `meta.lastModified` | `dateTime` | No | Read only | | | Not used |
| `meta.location` | `reference` | No | Read only | No | | Not used |
| `meta.version` | `string` | No | Read only | Yes | | Not used |
| `userName` | `string` | Yes | Read and write | No | Unique in your organization | Sign-in login name |
| `name` | `complex` | No | Read and write | | | |
| `name.formatted` | `string` | No | Read and write | No | | Not used |
| `name.familyName` | `string` | No | Read and write | No | | Last name |
| `name.givenName` | `string` | No | Read and write | No | | First name |
| `name.middleName` | `string` | No | Read and write | No | | Middle name |
| `name.honorificPrefix` | `string` | No | Read and write | No | | Name prefix |
| `name.honorificSuffix` | `string` | No | Read and write | No | | Name suffix |
| `displayName` | `string` | No | Read and write | No | | Display name |
| `nickName` | `string` | No | Read and write | No | | Nickname |
| `profileUrl` | `reference` | No | Read and write | No | | Not used |
| `title` | `string` | No | Read and write | No | | Job title |
| `userType` | `string` | No | Read and write | No | | User type |
| `preferredLanguage` | `string` | No | Read and write | No | | Preferred language |
| `locale` | `string` | No | Read and write | No | | Locale |
| `timezone` | `string` | No | Read and write | No | | Time zone |
| `active` | `boolean` | No | Read and write | | | Active or deactivated |
| `password` | `string` | No | Write only, never returned | No | | Not used |
| `emails` | `complex`, multi-valued | No | Read and write | | | |
| `emails.value` | `string` | No | Read and write | No | | Email ([which email](#email)) |
| `emails.display` | `string` | No | Read and write | No | | Not used |
| `emails.type` | `string` | No | Read and write | No | Suggested values: `work`, `home`, `other` | Email ([which email](#email)) |
| `emails.primary` | `boolean` | No | Read and write | | | Email ([which email](#email)) |
| `phoneNumbers` | `complex`, multi-valued | No | Read and write | | | |
| `phoneNumbers.value` | `string` | No | Read and write | No | | Work phone and mobile phone |
| `phoneNumbers.display` | `string` | No | Read and write | No | | Not used |
| `phoneNumbers.type` | `string` | No | Read and write | No | Suggested values: `work`, `home`, `mobile`, `fax`, `pager`, `other` | Work phone and mobile phone |
| `phoneNumbers.primary` | `boolean` | No | Read and write | | | Work phone and mobile phone |
| `ims` | `complex`, multi-valued | No | Read and write | | | |
| `ims.value` | `string` | No | Read and write | No | | Not used |
| `ims.display` | `string` | No | Read and write | No | | Not used |
| `ims.type` | `string` | No | Read and write | No | Suggested values: `aim`, `gtalk`, `icq`, `xmpp`, `msn`, `skype`, `qq`, `yahoo` | Not used |
| `ims.primary` | `boolean` | No | Read and write | | | Not used |
| `photos` | `complex`, multi-valued | No | Read and write | | | |
| `photos.value` | `reference` | No | Read and write | No | | Not used |
| `photos.display` | `string` | No | Read and write | No | | Not used |
| `photos.type` | `string` | No | Read and write | No | Suggested values: `photo`, `thumbnail` | Not used |
| `photos.primary` | `boolean` | No | Read and write | | | Not used |
| `addresses` | `complex`, multi-valued | No | Read and write | | | |
| `addresses.formatted` | `string` | No | Read and write | No | | Not used |
| `addresses.streetAddress` | `string` | No | Read and write | No | | Work address |
| `addresses.locality` | `string` | No | Read and write | No | | Work address |
| `addresses.region` | `string` | No | Read and write | No | | Work address |
| `addresses.postalCode` | `string` | No | Read and write | No | | Work address |
| `addresses.country` | `string` | No | Read and write | No | | Work address |
| `addresses.type` | `string` | No | Read and write | No | Suggested values: `work`, `home`, `other` | Work address |
| `addresses.primary` | `boolean` | No | Read and write | | | Work address |
| `groups` | `complex`, multi-valued | No | Read only | | | Directory groups (read only) |
| `groups.value` | `string` | No | Read only | No | | Not used |
| `groups.$ref` | `reference` | No | Read only | No | | Not used |
| `groups.display` | `string` | No | Read only | No | | Not used |
| `groups.type` | `string` | No | Read only | No | Suggested values: `direct`, `indirect` | Not used |
| `entitlements` | `complex`, multi-valued | No | Read and write | | | |
| `entitlements.value` | `string` | No | Read and write | No | | Not used |
| `entitlements.display` | `string` | No | Read and write | No | | Not used |
| `entitlements.type` | `string` | No | Read and write | No | | Not used |
| `entitlements.primary` | `boolean` | No | Read and write | | | Not used |
| `roles` | `complex`, multi-valued | No | Read and write | | | |
| `roles.value` | `string` | No | Read and write | No | | Not used |
| `roles.display` | `string` | No | Read and write | No | | Not used |
| `roles.type` | `string` | No | Read and write | No | | Not used |
| `roles.primary` | `boolean` | No | Read and write | | | Not used |
| `x509Certificates` | `complex`, multi-valued | No | Read and write | | | |
| `x509Certificates.value` | `binary` | No | Read and write | | | Not used |
| `x509Certificates.display` | `string` | No | Read and write | No | | Not used |
| `x509Certificates.type` | `string` | No | Read and write | No | | Not used |
| `x509Certificates.primary` | `boolean` | No | Read and write | | | Not used |

### Enterprise user

Schema URN: `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`

| Attribute | Type | Required | Mutability | Case-sensitive | Rules | Updates on the person |
| - | - | - | - | - | - | - |
| `employeeNumber` | `string` | No | Read and write | No | | Employee number |
| `costCenter` | `string` | No | Read and write | No | | Cost center |
| `organization` | `string` | No | Read and write | No | | Organization |
| `division` | `string` | No | Read and write | No | | Division |
| `department` | `string` | No | Read and write | No | | Department |
| `manager` | `complex` | No | Read and write | | | |
| `manager.value` | `string` | No | Read and write | No | | Manager |
| `manager.$ref` | `reference` | No | Read and write | No | | Not used |
| `manager.displayName` | `string` | No | Read only | No | | Not used |

### Living Security user

Schema URN: `urn:ietf:params:scim:schemas:extension:livingsecurity:2.0:User`

| Attribute | Type | Required | Mutability | Case-sensitive | Rules | Updates on the person |
| - | - | - | - | - | - | - |
| `startDate` | `string` | No | Read and write | No | | Start date |
| `location` | `string` | No | Read and write | No | | Location |
| `employmentType` | `string` | No | Read and write | No | Suggested values: `full-time`, `part-time`, `contractor`, `intern`, `temporary`, `vendor` | Employment type |

### Group

Schema URN: `urn:ietf:params:scim:schemas:core:2.0:Group`

| Attribute | Type | Required | Mutability | Case-sensitive | Rules | Updates on the person |
| - | - | - | - | - | - | - |
| `id` | `string` | No | Read only | Yes | Unique in your organization | Not used |
| `externalId` | `string` | No | Read and write | Yes | | Stored link to the IdP group |
| `meta` | `complex` | No | Read only | | | |
| `meta.resourceType` | `string` | No | Read only | Yes | | Not used |
| `meta.created` | `dateTime` | No | Read only | | | Not used |
| `meta.lastModified` | `dateTime` | No | Read only | | | Not used |
| `meta.location` | `reference` | No | Read only | No | | Not used |
| `meta.version` | `string` | No | Read only | Yes | | Not used |
| `displayName` | `string` | Yes | Read and write | No | | Directory group name |
| `members` | `complex`, multi-valued | No | Read and write | | | |
| `members.value` | `string` | No | Set once | No | | Directory group members |
| `members.$ref` | `reference` | No | Set once | No | | Not used |
| `members.display` | `string` | No | Read only | No | | Not used |
| `members.type` | `string` | No | Set once | No | Suggested values: `User`, `Group` | Not used |

## Paths in requests

* **Core attributes** take their plain name, for example `title` or `name.givenName`.
* **Extension attributes** use the full schema URN in a PATCH `path`, for example `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department`. A bare `department` in a PATCH path is refused with [LS-SCIM-1401](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1401). In a `POST` or `PUT` body, put extension attributes inside an object named by the URN.
* **Filters on multi-valued attributes** pick one value, for example `emails[type eq "work"].value` or `phoneNumbers[type eq "mobile"].value`.

```json theme={null}
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "urn:ietf:params:scim:schemas:extension:livingsecurity:2.0:User"
  ],
  "userName": "alex.rivera@example.com",
  "name": { "givenName": "Alex", "familyName": "Rivera" },
  "emails": [{ "value": "alex.rivera@example.com", "type": "work", "primary": true }],
  "title": "Analyst",
  "active": true,
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "Finance",
    "employeeNumber": "10442",
    "manager": { "value": "<the manager's SCIM user id>" }
  },
  "urn:ietf:params:scim:schemas:extension:livingsecurity:2.0:User": {
    "startDate": "2024-03-18",
    "location": "Austin",
    "employmentType": "full-time"
  }
}
```

## Notes on specific attributes

* **`manager.value`** must be the manager's SCIM user `id` in Living Security, not their email or a directory ID. Microsoft Entra ID sends this `id` when the manager is also provisioned. A value that matches no SCIM user links no manager. When the manager is provisioned after the person, the link is made on the next sync.
* **`phoneNumbers`:** the value with `type` `work` becomes the work phone and the value with `type` `mobile` becomes the mobile phone. Send numbers in international format, for example `+15125550100`.
* **`addresses`:** the primary address, else the `work` address, else the first one, becomes the work address.
* **`preferredLanguage` and `locale`:** `preferredLanguage` is the person's main language for the learner interface and messages. `locale` is the fallback. Send BCP 47 language tags such as `de` or `de-DE`. See [Language and locale](https://docs.livingsecurity.com/features/settings/scim.md#language-and-locale-for-localized-experiences).
* **`userType`** is shown as the person's user type. In Microsoft Entra ID, `userType` is `Member` or `Guest`. Map it only if that is useful in your reports.
* **`startDate`** accepts ISO dates (`YYYY-MM-DD`) and timestamps ending in `Z` or a UTC offset. It also accepts `MM/DD/YYYY` or `DD/MM/YYYY` when you select that input format in the **Employment start date** card next to the SCIM card. Select the Living Security extension's `startDate` field to use the value as the person's employment start date. ISO values remain valid with either slash format selected. The platform preserves the value in SCIM responses and stores the calendar date on the person; it never guesses the order of slash dates. Any other value, such as an impossible date or a slash date in the other order, is still saved and returned as sent, but it is not used as a start date: the person's start date shows as unreadable until the identity provider sends a value the platform can read. Remove the value or send `null` to clear it.
* **`employmentType`** accepts any text. Use the suggested values when you can, so reports group people the same way.
* **`groups`** on a user is read only. Living Security fills it from the groups your IdP sends. To change membership, send group changes. See [Groups and cohorts](https://docs.livingsecurity.com/features/settings/scim/groups.md).
* **`roles` and `entitlements`** are stored and returned, but never grant a role or access in Living Security.
* **A single value for a multi-valued attribute** is accepted. For example, `"roles": "Participant"` is read as `"roles": [{ "value": "Participant" }]`, and Living Security returns the list form. The value must still have the declared type: a number or `true` where the schema expects text returns `400` ([LS-SCIM-1104](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1104)).

## Custom extension schemas

Your IdP can send attributes in its own extension schema, for example `urn:ietf:params:scim:schemas:extension:yourcompany:2.0:User:costCenterCode`.

* Living Security stores each custom extension attribute and returns it to your IdP.
* After the first request that uses it, the extension appears in `GET /Schemas` for your connection, and in filters and PATCH paths.
* Custom extension attributes do not update the person's profile fields. For native SCIM, use the Living Security extension's `startDate` field as the source in the **Employment start date** card.
* Limits: 20 custom extension schemas on a resource, 200 attributes in one schema, and 256 characters in a schema URN. A request over a limit is refused with [LS-SCIM-1112](https://docs.livingsecurity.com/features/settings/scim/errors.md#ls-scim-1112).
* A name your IdP sends that is in no schema, such as a misspelled `titel` at the top level, is not stored. The **Attributes** tab lists it as **is not stored**.

## Mapping advice by identity provider

The examples below show common sources. Your directory may keep a value in another attribute. Check the result on the **Attributes** tab after you provision one test user. See [Test your SCIM setup](https://docs.livingsecurity.com/features/settings/scim/testing.md).

### Microsoft Entra ID

| Living Security attribute | Entra source | Advice |
| - | - | - |
| `userName` | `mail`, or `userPrincipalName` when it equals the email | Use the same source as the SSO NameID. Set it as the matching attribute, precedence 1. |
| `emails[type eq "work"].value` | `mail` | Required. |
| `active` | `Switch([IsSoftDeleted], , "False", "True", "True", "False")` | Deactivates the person when Entra disables or soft-deletes them. |
| `name.givenName`, `name.familyName` | `givenName`, `surname` | |
| `title` | `jobTitle` | |
| `userType` | `userType` | Optional. Entra sends `Member` or `Guest`. |
| `preferredLanguage` | `preferredLanguage`, or an `extensionAttributeNN` that holds the language | Map an extension attribute only when it holds a language tag. |
| `phoneNumbers[type eq "work"].value`, `phoneNumbers[type eq "mobile"].value` | `telephoneNumber`, `mobile` | |
| Enterprise `employeeNumber` | `employeeId` | Use the full URN as the target. |
| Enterprise `department` | `department` | Use the full URN as the target. |
| Enterprise `manager` | `manager` | Map to the Enterprise `manager`, not to a custom attribute. |

**Check an Entra mapping** on the **Validate** tab reads an Entra schema export and finds the common mistakes. See [Set up Microsoft Entra ID](https://docs.livingsecurity.com/features/settings/scim-microsoft-entra-id.md).

### Okta

| Living Security attribute | Okta source | Advice |
| - | - | - |
| `userName` | The Okta application username | Set the application username format to the email, the same value SSO sends. |
| `emails[type eq "work"].value` | `user.email` | Required. |
| `active` | Turn on **Deactivate Users** | Okta sends `active: false` when you unassign or deactivate a person. |
| `name.givenName`, `name.familyName` | `user.firstName`, `user.lastName` | |
| `title` | `user.title` | |
| `userType` | `user.userType` | Optional. |
| `preferredLanguage`, `locale` | `user.preferredLanguage`, `user.locale` | |
| Enterprise `employeeNumber`, `department` | `user.employeeNumber`, `user.department` | In the Profile Editor, the external namespace must be the Enterprise URN. |
| Enterprise `manager` | Leave unmapped | `user.managerId` holds a value from your directory, not the manager's Living Security SCIM `id`, so it links no manager. |

See [Set up Okta](https://docs.livingsecurity.com/features/settings/scim-okta.md).

### Other identity providers

Living Security SCIM follows RFC 7643 and RFC 7644. Any IdP that sends standard SCIM 2.0 can use these attributes.

* Map `userName` to the email your SSO sends, and map the same email to `emails[type eq "work"].value`, marked primary.
* Map `active` so that a removed person is sent as `active: false`.
* Send Enterprise attributes with their full schema URN.
* Use the Living Security extension for `startDate`, `location` and `employmentType`.

## Related

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


## Related topics

- [SCIM API reference and limits](https://docs.livingsecurity.com/features/settings/scim/api-reference.md)
- [SCIM and Google Workspace](https://docs.livingsecurity.com/features/settings/scim-google-workspace.md)
- [Set up SCIM with another SCIM 2.0 client](https://docs.livingsecurity.com/features/settings/scim-generic.md)


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