Help Center

Search
Log in
Sign up

Help Center

Log in
Sign up
Table of Contents

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

AttributeRequirement / accessSemantics
idRead-onlyImmutable SCIM resource UUID; not the canonical Workspace API user ID.
userNameRequired for POST/PUT; writableEmail-shaped source profile value; trimmed, maximum 254 characters. Case-insensitive matching within the source.
emailsOptional input; writableOne work email matching userName. Response always uses type work and primary true.
displayNameOptional; writableSource full name; trimmed, maximum 200 supplied characters. null clears it; absent from response when null.
externalIdOptional; writableOpaque source-local correlation string. Exact case-sensitive matching. null/removal clears it. Not account ownership proof.
activeOptional; writableDesired source lifecycle, not a guarantee of effective access. New User defaults to true; POST false is rejected.
urn:ietf:params:scim:schemas:extension:diggle:2.0:User:roleOptional; writableadmin, creator or runner. Initial default is the existing role on adoption, otherwise runner.
metaRead-onlyResource type, creation/modification timestamps and relative location. Do not supply ownership metadata.

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.

Parameter  Behavior
startIndexDefault 1; nonpositive values clamp to 1.
countDefault 100; capped at 200. Negative values clamp to 0. Zero returns only the total and an empty Resources array.
filterOptional supported equality expression. Other query parameters are rejected.
{
  "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.

Related articles