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
| Field | Type | Description |
|---|
emails | Array | 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:value (string, required): Email address.primary (boolean): Whether this is the primary email.type (string): Email type (for example, “work”).
|
Email (not userName) is requiredWhile 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.
Optional and behavioral fields
| Field | Type | Description |
|---|
userName | String | 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. |
active | Boolean | Default: true. Set to false to deactivate the user (revoke access). |
externalId | String | Identifier from the IdP. Used to map users between systems. |
name | Object | A complex object containing:givenName (string, max 256 chars): First name.familyName (string, max 256 chars): Last name.
|
LaunchDarkly extension attributes (roles)
LaunchDarkly lets you define roles using either the standard extension namespace or root-level attributes for convenience.
| Field | Type | Description |
|---|
role | String | 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. |
customRole | String | A comma-separated list of custom role keys (for example, "qa-team,release-mgr"). |
customRolesArray | Array | An array of custom role keys (for example, ["qa-team", "release-mgr"]). |
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:
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.
For an in-depth guide on how to use custom roles with IdPs, read Creating roles.
Read-only fields in responses
The following fields are automatically generated by LaunchDarkly and cannot be set or modified:
| Field | Type | Description |
|---|
id | String | 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. |
schemas | Array | An Array of SCIM schema identifiers |
meta | Object | A Metadata object containing:resourceType: Resource type (for example, “User”).created: Creation timestamp (Unix milliseconds).lastModified: Last modification timestamp (Unix milliseconds).location: URL to fetch this resource.version: Version number.
|
