SCIM provisioning - Hyperline

Use SCIM to provision users and groups for a SAML connection. Start with Single sign-on and user provisioning 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.
`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 for the accepted format.
Enterprise extension `manager.value` (optional)	—	The manager’s full provisioned SCIM user `id`. See 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:

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

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

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:

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.

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 for configuration and owner exclusions.

Update group membership

Use the user’s returned SCIM id as the member reference:

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:

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

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

​Endpoint and authentication

​User fields and SAML mapping

​Existing connections and identifier changes

​Update a user

​Repair missing fields on existing users

​Assign roles directly

​Assign a manager

​Update group membership

​Verify the Hyperline result

​Connection response limitations

​Related