SCIM 2.0 Provisioning

Keep shopper accounts in lockstep with your identity provider. SCIM automates the creation, update, and deprovisioning of Hygrade users so that a new hire in your HR system can place an order on day one — and a termination removes access immediately.

Overview

• Protocol: SCIM 2.0 (RFCs 7643 & 7644)
• Authentication: OAuth 2.0 bearer token
• Supported resources: User, Group
• Supported operations: Create, Read, Update (PUT & PATCH), Delete, List, Search (filter)
• Bulk operations: supported (max 100 operations per request)

Endpoints

Authentication

SCIM requests are authenticated with a long-lived OAuth 2.0 bearer token issued for the SCIM client credentials grant. Tokens are tenant-scoped and carry the users:read, users:write, and (if using groups) groups:read, groups:write scopes.

curl https://order.hygradebusiness.com/scim/v2/Users \
  -H "Authorization: Bearer hg_live_scim_8f3c9..."

Request a SCIM token from your implementation engineer; the token should be stored exclusively in your IdP’s secret store and rotated annually.

User schema

Hygrade implements the core SCIM User schema plus an enterprise extension with Hygrade-specific attributes.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:hygrade:2.0:User"
  ],
  "userName": "jane.doe@acmecorp.com",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "emails": [
    { "value": "jane.doe@acmecorp.com", "type": "work", "primary": true }
  ],
  "active": true,
  "urn:ietf:params:scim:schemas:extension:hygrade:2.0:User": {
    "custId": "ACME001",
    "login": "jdoe",
    "costCenter": "CC-4420",
    "department": "Marketing",
    "employeeId": "E-10472",
    "roles": ["buyer", "approver"]
  }
}

Extension attributes

Common operations

Create a user

Look up by username

Update a user (partial)

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "name.familyName", "value": "Doe-Smith" },
    { "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:hygrade:2.0:User:costCenter",
      "value": "CC-9900" }
  ]
}

Deactivate a user

Set active: false. The shopper is immediately prevented from signing in and cannot place new orders; order history is retained for compliance.

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

Delete a user

Hard-delete is supported but strongly discouraged for audited customers — prefer active: false.

Groups

SCIM groups are mapped onto Hygrade approval groups and cost-center groups. Create a group, then add members:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "North America Approvers",
  "members": [
    { "value": "7c1a5b24-e9f7-4a43-9dc0-9b3f1c2d4a80", "display": "jane.doe@acmecorp.com" }
  ]
}

Identity provider setup

Error responses

Errors conform to RFC 7644 §3.12.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "detail": "A user with this userName already exists in account ACME001.",
  "scimType": "uniqueness",
  "status": "409"
}

Common codes

• 400 invalidFilter — unsupported filter syntax.
• 401 — missing or invalid bearer token.
• 403 — token is valid but does not carry the required scope.
• 404 — user or group not found.
• 409 uniqueness — a user with the same userName already exists in the account.

Rate limits

• 100 requests per second per bearer token.
• Bulk operations count as a single request toward rate limits; operations inside a bulk are capped at 100.
• Backoff on 429 using the Retry-After header.