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

# SCIM provisioning

> Configure stable user identifiers, update users and group memberships, and troubleshoot existing SCIM connections.

Use SCIM to provision users and groups for a SAML connection. Start with [Single sign-on and user provisioning](/docs/account/enterprise-sso) to configure the connection and choose how Hyperline assigns roles.

## Endpoint and authentication

Copy the SCIM endpoint and bearer token from your connection's setup assistant. The SCIM token is separate from your Hyperline API key. Sandbox and production use separate connections and credentials; use the endpoint belonging to the account you want to update.

The examples below use placeholders for the SCIM domain, connection ID, token, and resource IDs. Replace the entire base URL with the one shown in your setup assistant. Do not send these requests to the Hyperline public API host.

Treat returned resource IDs as opaque strings. Preserve the full value, including any provider prefix. URL-encode IDs in request paths, but use their original, unencoded value in JSON bodies.

## User fields and SAML mapping

Configure the following fields in your identity provider. Apart from `NameID`, the SAML column uses the short attribute names; use the full names shown in the setup assistant.

| SCIM field | SAML attribute | Value and purpose |
| - | - | - |
| `id` | — | Resource ID returned by the SCIM connection. Use the full value for updates, group membership references, and manager references. Do not construct or change it yourself. |
| `externalId` | — | The stable ID assigned by your provisioning system, such as an IGA UUID. Use it for reconciliation and keep it unchanged when names or emails change. |
| `userName` | `NameID` and `name` | The member's login name, usually their email address. For connections configured with the username mapping, send the exact same value as SAML `NameID`. Updating this field does not change `id`, `externalId`, or the primary email. |
| Primary `emails` entry | `emailaddress` | The member's current email address. Coordinate changes with the existing Hyperline membership before sign-in; see [email changes](/docs/account/enterprise-sso#connect-your-identity-provider). |
| `active` | — | The member's current status: `true` for active, `false` for suspended. |
| `roles` (optional) | — | Configure only when assigning Hyperline roles directly through SCIM. See [Assign roles directly](#assign-roles-directly) for the accepted format. |
| Enterprise extension `manager.value` (optional) | — | The manager's full provisioned SCIM user `id`. See [Assign a manager](#assign-a-manager). |

For connections configured with the username mapping, set SAML `NameID` to the same value as SCIM `userName`. If your identity provider also sends an explicit `nameidentifier` attribute, keep its value aligned with `NameID`. Keep the current email address in `emailaddress`. You do not need a separate Hyperline username.

Your SAML identity provider and provisioning service can be separate systems: send the email address in `NameID` and `userName`, and retain the provisioning service's UUID in `externalId`. You do not need to copy that UUID into the SAML identity provider.

The same person can have a resource in each environment. Store returned SCIM IDs per connection, even when the email and `externalId` are identical across environments.

### Existing connections and identifier changes

Existing connections may still use `externalId` to construct login identities. A connection configuration change affects newly created identities only; it does not migrate users already provisioned with UUID-based identities. Reopening the setup assistant does not migrate those accounts either.

Before switching an existing connection to email-based SAML identifiers:

1. Contact Hyperline through the in-app chat. Specify the account and environment, and provide one user's current SCIM `id`, `externalId`, `userName`, and SAML `NameID`. Keep the current sign-in mapping until the migration is coordinated.
2. Hyperline confirms the connection mapping and migrates any existing identities that need it, preserving their SCIM resource IDs, provisioning identifiers, memberships, and roles. Sandbox and production must be checked separately.
3. Once the identities are ready, configure your SAML provider to send the exact SCIM `userName` as `NameID`. Keep the provisioning system's original UUID in `externalId` and continue addressing SCIM updates using the returned `id`.
4. Verify sign-in with an existing member and a newly provisioned member. Confirm both can access the expected account with the expected role, and that SCIM updates still reach the existing member.

If you need to reopen the connection's setup assistant, use **Settings > General > Single sign-on > Reconfigure** in Hyperline. See [Manage your connection](/docs/account/enterprise-sso#manage-your-connection) for the provisioning settings to review afterward.

A later username or email rename also needs coordination before your SAML provider sends the new `NameID`. A successful PATCH of `userName` or `externalId` updates the stored field but does not change the login identity or SCIM resource ID. Restoring a missing `externalId` means sending its original value, not replacing a UUID with an email address.

## Update a user

Send a SCIM PATCH to the existing resource. This example changes only `userName`; it preserves the email and stable identifiers:

```sh theme={null}
curl --request PATCH \
  'https://<scim-domain>/scim/v2/connections/<connection-id>/Users/<url-encoded-user-id>' \
  --header 'Authorization: Bearer <SCIM token>' \
  --header 'Content-Type: application/scim+json' \
  --data '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {"op": "replace", "path": "userName", "value": "alex@example.com"}
    ]
  }'
```

To change the email too, update the primary `emails` entry explicitly and align the SAML email attribute. [Coordinate email changes](/docs/account/enterprise-sso#connect-your-identity-provider) before the member signs in with the new address.

### Repair missing fields on existing users

Enabling a mapping does not backfill older resources. First confirm the connection maps the required attribute; contact Hyperline through the in-app chat if an existing connection drops it. Then PATCH the existing user with the authoritative value from your identity provider.

Use the same request format above with the relevant operation:

| Field | PATCH operation | Verification |
| - | - | - |
| Missing `active` | `{"op":"replace","path":"active","value":true}` for an active user, or `false` for a suspended user | A subsequent GET includes the explicit status. Do not infer suspension from an absent field or reactivate everyone to fill it. |
| Missing `externalId` | `{"op":"replace","path":"externalId","value":"employee-1042"}` using the user's original immutable identity provider ID | GET the resource by `id`, then retry the `externalId` filter after indexing catches up. |
| Outdated `userName` | `{"op":"replace","path":"userName","value":"alex@example.com"}` | GET the resource and confirm the stored `userName`; this does not migrate the login identity or update the email. Coordinate [identifier changes](#existing-connections-and-identifier-changes) before sign-in. |

These updates preserve the SCIM resource ID. Never invent a replacement `externalId` or recreate a user just to fill missing data.

Filter by the stored `externalId`:

```sh theme={null}
curl --get \
  'https://<scim-domain>/scim/v2/connections/<connection-id>/Users' \
  --header 'Authorization: Bearer <SCIM token>' \
  --data-urlencode 'filter=externalId eq "employee-1042"'
```

Filtered reads can lag behind a successful write. Keep the returned resource ID and retry with backoff; an immediate empty search result is not a reason to create another user. If lookup remains empty or creation returns a conflict, contact Hyperline through the in-app chat before deleting or recreating identities.

## Assign roles directly

Use an array of role objects, not an array of strings. Set `value` to an existing role's exact name or ID in the target Hyperline account:

```sh theme={null}
curl --request PATCH \
  'https://<scim-domain>/scim/v2/connections/<connection-id>/Users/<url-encoded-user-id>' \
  --header 'Authorization: Bearer <SCIM token>' \
  --header 'Content-Type: application/scim+json' \
  --data '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {"op": "replace", "path": "roles", "value": [{"value": "Admin"}]}
    ]
  }'
```

Send one role, or mark exactly one entry as `primary: true` when sending several. Unknown or ambiguous roles prevent the Hyperline member update from being applied; SCIM does not create roles.

A direct role takes precedence over group mappings. Replacing `roles` with `[]` selects the default role, even when group role synchronization is enabled. Omitting `roles` leaves the previously stored value in place. Neither operation hands role management back to groups. Contact Hyperline before switching methods; see the [role assignment rules](/docs/account/enterprise-sso#choose-how-roles-are-managed).

## Assign a manager

Provision the manager through the same connection first. Send the manager's full returned SCIM user `id` in the enterprise extension's `manager.value`. A raw identity provider user ID, email, or `externalId` is not a substitute.

The manager must also belong to the same Hyperline account and cannot be the user being updated. An unresolved manager can prevent the entire Hyperline member update from being applied, including other supplied fields. Provision the manager, then resend the dependent user's update.

An explicit empty or null manager value clears the assignment. Omitting the field preserves it. See [Assign managers through SCIM](/docs/account/enterprise-sso#assign-managers-through-scim) for configuration and owner exclusions.

## Update group membership

Use the user's returned SCIM `id` as the member reference:

```sh theme={null}
curl --request PATCH \
  'https://<scim-domain>/scim/v2/connections/<connection-id>/Groups/<group-id>' \
  --header 'Authorization: Bearer <SCIM token>' \
  --header 'Content-Type: application/scim+json' \
  --data '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {"op": "add", "path": "members", "value": [{"value": "<full-scim-user-id>"}]}
    ]
  }'
```

To remove that member, use this operation in the same PATCH envelope:

```json theme={null}
{
  "op": "remove",
  "path": "members[value eq \"<full-scim-user-id>\"]"
}
```

A successful group PATCH can return `204 No Content`. Read `GET /Groups/{id}` to check membership: the group collection response can contain an empty `members` array even when the group has members.

Group role assignment requires both user provisioning and group role synchronization to be enabled, with saved mappings. Membership changes then update roles without a new SAML login. SAML group assertions do not replace SCIM group updates. Direct user roles still take precedence; see [Configure group mappings](/docs/account/enterprise-sso#configure-your-chosen-role-management-method).

## Verify the Hyperline result

A successful SCIM response confirms the directory accepted the request. Hyperline processes membership changes asynchronously. Check **Settings > Team > Members** after processing, and **View groups > View members** in role provisioning for group changes.

If the member remains unchanged, confirm the account's connection and provisioning settings, then check supplied roles and manager references. Correct invalid values and resend the update. Contact Hyperline through the in-app chat with the affected resource ID and request time if it still does not apply. Do not include bearer tokens.

Suspension and deletion follow the [membership lifecycle rules](/docs/account/enterprise-sso#manage-your-connection). In particular, another active identity for the same member in the same connection keeps their membership; account owners are excluded from automatic removal. Separate sandbox and production identities are expected. Do not merge or delete them based on matching email alone.

## Connection response limitations

The Auth0-backed SCIM endpoint has the following behavior:

| Response | Integration handling |
| - | - |
| `/Schemas`, `/ResourceTypes`, and `/ServiceProviderConfig` return `404` | Configure your connector explicitly using the setup assistant and this reference. Automatic SCIM discovery is unavailable. |
| Group collection entries contain empty `members` | Read the individual group resource to inspect membership. |
| User entries in a collection omit per-resource `schemas` | Do not rely on each collection entry repeating the schema list returned by an individual user read. |
| `meta.location` is relative | Resolve it against your configured SCIM origin. |
| An empty role list is returned as `[{}]` | Hyperline normalizes it to an empty assignment and applies the default role. |

## Related

* [Single sign-on and user provisioning](/docs/account/enterprise-sso)
* [Users & permissions](/docs/account/users-permissions)


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