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

# SCIM user schema and attributes

<View title="Developer" />

<View title="Federal docs" />

<View title="EU docs" />

This topic explains the user schema and attributes that the LaunchDarkly System for Cross-domain Identity Management (SCIM) API supports, including the LaunchDarkly extension attributes for roles.

LaunchDarkly uses the standard SCIM 2.0 user schema (`urn:ietf:params:scim:schemas:core:2.0:User`) and supports a custom extension schema (`urn:ietf:params:scim:schemas:extension:launchdarkly:2.0:User`) for LaunchDarkly-specific permissions.

## Required fields

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`emails`</td>
      <td>Array</td>
      <td>At least one email is required. The `value` must be a valid email address and must be unique within the account. Each email object can include:<ul><li>`value` (string, required): Email address.</li><li>`primary` (boolean): Whether this is the primary email.</li><li>`type` (string): Email type (for example, "work").</li></ul></td>
    </tr>
  </tbody>
</table>

<Note>
  **Email (not userName) is required**

  While the SCIM 2.0 standard typically requires `userName`, the LaunchDarkly implementation requires `emails` instead. The `userName` field is optional and defaults to the email address if not provided. Most identity providers (IdPs) should map their unique identifier to the `userName` field for proper user matching.
</Note>

## Optional and behavioral fields

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`userName`</td>
      <td>String</td>
      <td>**Recommended.** While SCIM standards typically require this, LaunchDarkly relies on `email` as the primary identifier. If `userName` is omitted, the API defaults it to the email address. The value is in lowercase and trimmed.</td>
    </tr>

    <tr>
      <td>`active`</td>
      <td>Boolean</td>
      <td>Default: `true`. Set to `false` to deactivate the user (revoke access).</td>
    </tr>

    <tr>
      <td>`externalId`</td>
      <td>String</td>
      <td>Identifier from the IdP. Used to map users between systems.</td>
    </tr>

    <tr>
      <td>`name`</td>
      <td>Object</td>
      <td>A complex object containing:<ul><li>`givenName` (string, max 256 chars): First name.</li><li>`familyName` (string, max 256 chars): Last name.</li></ul></td>
    </tr>
  </tbody>
</table>

## LaunchDarkly extension attributes (roles)

LaunchDarkly lets you define roles using either the standard extension namespace or root-level attributes for convenience.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`role`</td>
      <td>String</td>
      <td>The built-in role: `"reader"`, `"writer"`, `"admin"`, or `"noAccess"`. Default: `"reader"` (or the Security Assertion Markup Language (SAML) default role if configured). Cannot be `"owner"` on create/update.</td>
    </tr>

    <tr>
      <td>`customRole`</td>
      <td>String</td>
      <td>A comma-separated list of custom role keys (for example, `"qa-team,release-mgr"`).</td>
    </tr>

    <tr>
      <td>`customRolesArray`</td>
      <td>Array</td>
      <td>An array of custom role keys (for example, `["qa-team", "release-mgr"]`).</td>
    </tr>
  </tbody>
</table>

Root-level fields, such as `role`, take precedence over fields that are nested in the extension namespace. If both `customRolesArray` and `customRole` are provided, `customRolesArray` takes precedence.

You can also use the extension namespace format, which is useful for IdPs like Azure Entra ID:

```json lines wrap theme={null}
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:launchdarkly:2.0:User"
  ],
  "emails": [{"value": "user@example.com"}],
  "urn:ietf:params:scim:schemas:extension:launchdarkly:2.0:User": {
    "role": "admin",
    "customRole": "custom-role-1"
  }
}
```

You cannot create new custom attributes using the SCIM API, but you can set the `role` and `customRole` attributes for SCIM users. For SAML-based single sign-on (SSO), LaunchDarkly supports mapping only the `role`, `customRole`, and `teamKey` attributes.

To learn more about these attributes, read [Roles](/docs/home/account/roles).

For an in-depth guide on how to use custom roles with IdPs, read [Creating roles](/docs/guides/teams-roles/custom-roles).

## Read-only fields in responses

The following fields are automatically generated by LaunchDarkly and cannot be set or modified:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`id`</td>
      <td>String</td>
      <td>The LaunchDarkly member ID, used for updates and deletes. This ID is permanent, and does not change even if the member's email address changes.</td>
    </tr>

    <tr>
      <td>`schemas`</td>
      <td>Array</td>
      <td>An Array of SCIM schema identifiers</td>
    </tr>

    <tr>
      <td>`meta`</td>
      <td>Object</td>
      <td>A Metadata object containing:<ul><li>`resourceType`: Resource type (for example, "User").</li><li>`created`: Creation timestamp (Unix milliseconds).</li><li>`lastModified`: Last modification timestamp (Unix milliseconds).</li><li>`location`: URL to fetch this resource.</li><li>`version`: Version number.</li></ul></td>
    </tr>
  </tbody>
</table>