SCIM User Reference

Reference for Diggle’s supported SCIM User attributes and update behavior. All calls require a Bearer provisioning token and are scoped to its workspace and provisioning source.

User representation

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:diggle:2.0:User"
  ],
  "id": "<scim-user-id>",
  "userName": "[email protected]",
  "emails": [
    {
      "value": "[email protected]",
      "type": "work",
      "primary": true
    }
  ],
  "displayName": "Example Trainer",
  "externalId": "example-provider-object",
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2026-10-08T12:00:00.000Z",
    "lastModified": "2026-10-08T12:00:00.000Z",
    "location": "/scim/v2/Users/<scim-user-id>"
  },
  "urn:ietf:params:scim:schemas:extension:diggle:2.0:User": {
    "role": "runner"
  }
}

Example identifiers and timestamps are placeholders. Use the returned UUID as {id} in subsequent User requests.

Attributes

Create and replace

POST /Users creates only; it is not an upsert. Duplicate creation returns 409 uniqueness. PUT /Users/{id} requires userName and replaces the supported source profile: omitted displayName and externalId are cleared, while omitted active and role are preserved.

If emails is supplied, it must contain exactly one value. Its type may be omitted, null or work; primary may be omitted or true. Multiple entries, non-work types, labels, primary=false, empty arrays, clears and conflicting aliases are rejected. When equivalent aliases are both supplied, userName spelling wins.

PATCH

PATCH accepts 1–100 Operations, applied atomically. Attribute/path and operation names are case-insensitive. Omitted fields are preserved. Add/replace supports userName, emails, emails[type eq “work”].value, displayName, externalId, active and the Diggle role extension. Remove supports displayName and externalId only. Source email and role cannot be removed.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": false
    }
  ]
}

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:diggle:2.0:User:role",
      "value": "creator"
    }
  ]
}

Pathless add/replace objects with supported attributes are accepted. Prefer JSON booleans for active. Legacy true/false strings are accepted only for PATCH active; POST/PUT require booleans. Conflicting email aliases within one request reject the complete update.

Filtering and pagination

userName eq "[email protected]"
externalId eq "example-provider-object"
emails[type eq "work"].value eq "[email protected]"

Only quoted equality predicates are supported. Up to eight may be joined by AND, with at most four parenthesis levels and a 1024-character filter. OR, NOT, other operators and null literals return 400 invalidFilter. Email comparisons trim and ignore case; externalId is exact.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 0,
  "startIndex": 1,
  "itemsPerPage": 0,
  "Resources": []
}

Profile and identity boundaries

SCIM profile values describe the provisioning source’s user. They may initialize a newly created Diggle account, but later source email, displayName or externalId changes do not automatically rewrite the global Diggle login/recovery email or account name. Updates remain bound to the same SCIM resource and account; they do not relink SSO or transfer account ownership.

An active=true response describes source intent. A pending invitation can remain pending, and local blocking or workspace suspension can still prevent effective access. No ETag or conditional-write contract is provided.

Microsoft Entra interoperability

For the minimal Entra mapping, use userPrincipalName for both userName and the work email, displayName for displayName, objectId for externalId, and a lifecycle expression with a Boolean active target. See Configure Microsoft Entra SCIM Provisioning for setup and lifecycle tests.

For Entra first-sign-in activation, externalId must contain the correct Microsoft object ID and the provisioning credential must identify the intended tenant. Changing externalId may invalidate an unused activation; it does not transfer an established Microsoft identity. Standard Core User and PatchOp schemas are supported. An Enterprise User schema declaration may be accepted with an empty extension object, but HR and other Enterprise User attributes are not supported.

Supported scope

Use the Users and discovery operations documented in setup. Groups, Bulk, sorting, attribute projection, ETags and conditional updates are not supported. SCIM does not create private project grants. Use active=false to remove managed workspace access; terminal DELETE is unsupported.

Related articles

• Set Up SCIM Provisioning
• SCIM User Lifecycle
• API & SCIM Errors