Users Endpoint

The /Users endpoint provides CRUD operations for user resources. It follows the SCIM 2.0 (System for Cross-domain Identity Management) core schema, which defines the User JSON shape. It also follows the SCIM 2.0 protocol, which defines the HTTP verbs, filter syntax, and pagination.

Every example uses the organization's SCIM provisioning token ($SCIM_TOKEN). See Authentication for the other accepted credentials. Writes are subject to the organization's provisioning policy: a switched-off operation returns 403 with scimType: mutability before anything is changed.

List Users

GET /orgs/\{orgId\}/api/v1/scim2.0/Users

Query Parameters

Parameter	Type	Description
filter	string	SCIM filter expression (e.g., userName eq "john@acme.com")
startIndex	integer	1-based index of first result (default: 1)
count	integer	Maximum results to return (default: 100, max: 200)
sortBy	string	Attribute to sort by (e.g., userName, name.familyName)
sortOrder	string	ascending or descending
attributes	string	Comma-separated list of attributes to return
excludedAttributes	string	Comma-separated list of attributes to exclude

Filter Examples

# Filter by username
GET /scim2.0/Users?filter=userName eq "john@acme.com"

# Filter by active status
GET /scim2.0/Users?filter=active eq true

# Complex filter
GET /scim2.0/Users?filter=name.familyName sw "Sm" and active eq true

# Include soft-deleted
GET /scim2.0/Users?filter=isSoftDeleted eq true

# Value-path filter on emails
GET /scim2.0/Users?filter=emails[type eq "work" and value ew "@acme.com"]

An unsupported attribute or a malformed filter returns 400 invalidFilter; it never falls back to listing every user. The full grammar and the filterable attributes are in Filter Syntax.

Response

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 42,
  "startIndex": 1,
  "itemsPerPage": 10,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "123",
      "userName": "john@acme.com",
      "name": {
        "formatted": "John Smith",
        "familyName": "Smith",
        "givenName": "John"
      },
      "emails": [
        {"value": "john@acme.com", "primary": true, "type": "work"}
      ],
      "active": true,
      "meta": {
        "resourceType": "User",
        "created": "2024-01-01T00:00:00Z",
        "lastModified": "2024-06-15T12:30:00Z",
        "location": "https://app.lumoauth.dev/orgs/acme-corp/api/v1/scim2.0/Users/123",
        "version": "W/\"5\""
      }
    }
  ]
}

Get User

GET /orgs/\{orgId\}/api/v1/scim2.0/Users/\{id\}

curl -X GET "https://app.lumoauth.dev/orgs/acme-corp/api/v1/scim2.0/Users/123" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Accept: application/scim+json"

Create User

POST /orgs/\{orgId\}/api/v1/scim2.0/Users

curl -X POST "https://app.lumoauth.dev/orgs/acme-corp/api/v1/scim2.0/Users" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane@acme.com",
    "name": {
      "givenName": "Jane",
      "familyName": "Doe"
    },
    "emails": [
      {"value": "jane@acme.com", "primary": true, "type": "work"}
    ],
    "password": "SecurePassword123!",
    "active": true
  }'

• Password. Optional. It must satisfy the organization's password policy and the breached-password check; otherwise the request fails with 400 invalidValue and the policy message, and nothing is created.
• active. An explicit value wins. When active is omitted, the organization's Auto-activate new users setting determines the result. When that setting is off, the user starts inactive until an administrator (or a later SCIM active: true) enables them.
• Duplicate userName returns 409 uniqueness.

Update User (Replace)

PUT /orgs/\{orgId\}/api/v1/scim2.0/Users/\{id\}

Replace the entire user resource. Include all required attributes.

Attributes that the organization marked as protected (email, name, active) keep their local value; the rest of the update is applied. roles and permissions are never writable here. Refused with 403 when Allow user updates is off.

A new password is checked against the password policy and breached-password list (400 invalidValue on failure, nothing applied). When it is accepted, the user is signed out everywhere and their OAuth access and refresh tokens are revoked. Passwords of administrator accounts are never changed through SCIM.

Partial Update (PATCH)

PATCH /orgs/\{orgId\}/api/v1/scim2.0/Users/\{id\}

PATCH supports add, replace, and remove operations. Operations that target a protected attribute (emails, name.*, displayName, active) are dropped and the remaining operations still apply. Refused with 403 when Allow user updates is off.

• Value-path targets such as emails[type eq "work"].value are evaluated against the value that LumoAuth stores. If the stored value does not match the filter, the operation is skipped rather than overwriting it. If there is no stored value, add and replace set it and remove does nothing. A malformed filter in a path returns 400 invalidValue.
• Password operations follow the same rules as PUT: policy and breached-password check, then sign-out everywhere and token revocation. On an administrator account a password operation returns 403 mutability.

curl -X PATCH "https://app.lumoauth.dev/orgs/acme-corp/api/v1/scim2.0/Users/123" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {"op": "replace", "path": "active", "value": false},
      {"op": "replace", "path": "name.givenName", "value": "Johnny"}
    ]
  }'

Delete User

DELETE /orgs/\{orgId\}/api/v1/scim2.0/Users/\{id\}

Deprovisioning action

What DELETE does is chosen per organization (portal > Integrations > SCIM provisioning > Inbound SCIM > Deprovisioning action). The default is a soft delete: the user disappears from lists, active sessions end, and an administrator can restore the account. deactivate keeps the row visible but blocks sign-in (active: false), so the IdP can re-enable it later. hard_delete removes the record at once. Refused with 403 when Allow user deletion is off.

# Deprovision (soft delete by default)
curl -X DELETE "https://app.lumoauth.dev/orgs/acme-corp/api/v1/scim2.0/Users/123" \
  -H "Authorization: Bearer $SCIM_TOKEN"

# Remove a soft-deleted user permanently
curl -X DELETE "https://app.lumoauth.dev/orgs/acme-corp/api/v1/scim2.0/Users/123?isSoftDeleted=true" \
  -H "Authorization: Bearer $SCIM_TOKEN"

Policy refusal:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "403",
  "scimType": "mutability",
  "detail": "User deletion is disabled by this organization's SCIM provisioning policy"
}

User Schema

Attribute	Type	Mutability	Description
id	string	readOnly	Unique identifier
userName	string	readWrite	Unique username (email)
externalId	string	readWrite	External system identifier
name.formatted	string	readWrite	Full formatted name
name.givenName	string	readWrite	First name
name.familyName	string	readWrite	Last name
displayName	string	readWrite	Display name
emails	array	readWrite	Email addresses
phoneNumbers	array	readWrite	Phone numbers
active	boolean	readWrite	Account active status
password	string	writeOnly	Password (never returned). Must meet the password policy. Ignored on PUT and refused on PATCH for administrator accounts.
meta	object	readOnly	Resource metadata

roles and permissions are not writable through /Users; manage membership through Groups.

Standards used on this page

Plain name	Standard
SCIM 2.0 (user and group provisioning)	RFC 7642, RFC 7643 and RFC 7644

See the standards reference for what each one covers and how LumoAuth uses it.