SCIM Provisioning

SCIM (System for Cross-domain Identity Management) lets your Identity Provider (IdP) automatically create, update, and deactivate users in Linkinize, and manage access to SCIM-managed workspaces.

In Linkinize:

• SCIM tenant = Organization
• SCIM User = Organization membership
• SCIM Group = Workspace
• SCIM Group membership = Workspace membership

Quick start

1. In Linkinize, open your Organization.
2. Go to Plugins -> SCIM.
3. Enable SCIM and generate a provisioning token.
4. In your IdP, configure SCIM provisioning with:
   • Base URL: use the SCIM Base URL shown in Linkinize (it looks like https://app.linkinize.com/scim/v2).
   • Authorization: Bearer <token>

Notes:

• The token is shown once. Store it in your IdP.
• Revoking the token disables provisioning for that organization.

What Linkinize supports

Users

• Create users in the organization
• Update name (given/family)
• Deactivate/reactivate organization access via active
• Idempotent creates using externalId
• Filtering by userName (email) or externalId

Workspaces (Groups)

• Create SCIM-managed workspaces
• Rename SCIM-managed workspaces
• Delete SCIM-managed workspaces
• Manage membership of SCIM-managed workspaces (add/remove/replace)
• Idempotent creates using externalId
• Filtering by displayName or externalId

What is intentionally NOT supported

• SCIM Bulk operations (/Bulk)
• Password management (SCIM changePassword)
• Sorting and ETags
• Editing non-SCIM-managed organization memberships (manual/invited users)
• Editing or deleting non-SCIM-managed workspaces
• Deleting users globally (Linkinize never hard-deletes users via SCIM)
• DELETE /Users (deprovisioning is done via active=false)

Provisioning flow (how most IdPs talk to SCIM)

Most IdPs follow a variation of this sequence:

1. Discovery (optional but common)

   • GET /ServiceProviderConfig
   • GET /Schemas
   • GET /ResourceTypes

2. User sync

   • Check if the user exists (often via filter): GET /Users?filter=userName eq "[email protected]"
   • Create if missing: POST /Users
   • Deactivate when unassigned/offboarded: PATCH /Users/{id} set active=false
   • Reactivate when re-assigned: PATCH /Users/{id} set active=true

3. Group/workspace sync

   • Create a workspace for a group: POST /Groups
   • Manage membership:
     • Incremental: PATCH /Groups/{id} add/remove members
     • Full replace: PUT /Groups/{id} or PATCH with replace on members
   • Delete a SCIM-managed workspace when the group is deleted: DELETE /Groups/{id}

Linkinize is designed to be idempotent under retries: repeated creates with the same externalId return the existing resource.

API details

Base path: /scim/v2

Auth: Bearer token (organization-scoped)

Headers

Authorization: Bearer <scim_token>
Content-Type: application/scim+json
Accept: application/scim+json

Users

Supported endpoints:

• GET /Users
• POST /Users
• GET /Users/{id}
• PATCH /Users/{id}
• PUT /Users/{id}

Supported attributes:

• userName (email)
• name.givenName, name.familyName
• active
• externalId

Filtering:

• GET /Users?filter=userName eq "[email protected]"
• GET /Users?filter=externalId eq "idp-user-123"

Groups (Workspaces)

Supported endpoints:

• GET /Groups
• POST /Groups
• GET /Groups/{id}
• PATCH /Groups/{id}
• PUT /Groups/{id}
• DELETE /Groups/{id}

Supported attributes:

• displayName
• members (array of { "value": "<user_id>" })
• externalId

Filtering:

• GET /Groups?filter=displayName eq "Engineering"
• GET /Groups?filter=externalId eq "idp-group-456"

Membership semantics

For a SCIM-managed workspace:

• PATCH add members adds memberships if missing (no duplicates)
• PATCH remove members removes only SCIM-managed memberships
• PUT / PATCH replace members replaces only the SCIM-managed member set; manually-added members are kept

Examples

Replace https://app.linkinize.com with the base domain shown in Linkinize, and set SCIM_TOKEN.

List users

curl -sS "https://app.linkinize.com/scim/v2/Users?startIndex=1&count=100" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Accept: application/scim+json"

Create a user

curl -sS "https://app.linkinize.com/scim/v2/Users" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d @- <<'JSON'
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "[email protected]",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "active": true,
  "externalId": "idp-user-123"
}
JSON

Deactivate (deprovision) a user

curl -sS -X PATCH "https://app.linkinize.com/scim/v2/Users/<user_id>" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d @- <<'JSON'
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {"op": "replace", "path": "active", "value": false}
  ]
}
JSON

Create a workspace (Group) with members

curl -sS "https://app.linkinize.com/scim/v2/Groups" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d @- <<'JSON'
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering",
  "externalId": "idp-group-456",
  "members": [
    {"value": "<user_id_1>"},
    {"value": "<user_id_2>"}
  ]
}
JSON

Add a member (incremental)

curl -sS -X PATCH "https://app.linkinize.com/scim/v2/Groups/<group_id>" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d @- <<'JSON'
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [{"value": "<user_id>"}]
    }
  ]
}
JSON

Remove a member (Azure/Entra style)

curl -sS -X PATCH "https://app.linkinize.com/scim/v2/Groups/<group_id>" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d @- <<'JSON'
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"<user_id>\"]"
    }
  ]
}
JSON

Delete a SCIM-managed workspace

curl -sS -X DELETE "https://app.linkinize.com/scim/v2/Groups/<group_id>" \
  -H "Authorization: Bearer $SCIM_TOKEN"

Errors and troubleshooting

• 401 Unauthorized: missing/invalid token (also happens after token revoke/disable)
• 403 Forbidden: SCIM not available on your plan, or quota exceeded, or attempt to deactivate the last active org admin
• 404 Not Found: resource does not exist
• 409 Conflict: trying to manage a non-SCIM-managed user/workspace (manual membership/workspace)

If your IdP fails on group membership updates:

• Ensure the workspace was created via SCIM (only SCIM-managed workspaces can be updated via SCIM).
• Ensure the user exists in the organization (create/sync the user first).