SCIM Integration

Authentication

All SCIM endpoints require a Bearer token issued via the OAuth 2.0 client_credentials grant (RFC 6749).

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=okta-acme-a1b2c3d4&client_secret=<secret>&scope=governance:scim

• Grant type: client_credentials only
• Auth method: client_secret_post (credentials in form body, not Basic auth header)
• Token algorithm: ES256 (ECDSA P-256, key published at /.well-known/jwks.json)
• Token TTL: 3600 seconds
• Tokens include a jti claim for replay protection — each token may only be used once within its TTL window
• Required scope for SCIM: governance:scim

Base URL

https://governance.taskhawktech.com/scim/v2

Supported Endpoints

Method	Path	Description
GET	/Users	List operators (supports startIndex, count, filter)
POST	/Users	Establish identity mapping (idempotent)
GET	/Users/{id}	Get operator by SCIM ID
PATCH	/Users/{id}	Update operator (supports active=false for deprovisioning)
DELETE	/Users/{id}	Deactivate operator (same as PATCH active=false)
GET	/Groups	List groups (empty — Kevros uses API keys, not groups)
GET	/ServiceProviderConfig	Capability advertisement
GET	/ResourceTypes	Resource type discovery
GET	/Schemas	Schema discovery

Filtering

The GET /Users endpoint supports the following SCIM filter expressions:

GET /scim/v2/Users?filter=userName eq "operator@example.com"
GET /scim/v2/Users?filter=id eq "scim-uuid-here"

Only the eq operator is supported. Filterable attributes: userName and id.

User Lifecycle Semantics

Kevros operators are provisioned out-of-band via the signup flow or admin panel. SCIM establishes the identity mapping between your IdP directory and the Kevros operator record — it does not create new operator accounts.

• POST /Users — If an operator with the given userName already exists, returns 200 with the existing record (idempotent). Returns 404 if no matching operator is provisioned.
• PATCH /Users/{id} with active: false — Triggers deprovisioning (see below).
• DELETE /Users/{id} — Same effect as PATCH with active=false. The operator record is deactivated, not deleted.

Deprovisioning Behavior

Deprovisioning is provenance-first. The sequence is deterministic and fail-closed on audit:

1. IdP sends PATCH or DELETE with active=false
2. Gateway writes a scim_deprovision record to the hash-chained provenance ledger
3. Only after the provenance write succeeds: enforcement_mode is set to deny
4. All subsequent governance calls from that operator return DENY until manual re-enablement

If the provenance write fails, the mode flip does NOT happen. This is fail-closed on audit integrity.

ServiceProviderConfig

The GET /ServiceProviderConfig endpoint advertises:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "documentationUri": "https://www.taskhawktech.com/docs/scim",
  "patch": { "supported": true },
  "bulk": { "supported": false, "maxOperations": 0, "maxPayloadSize": 0 },
  "filter": { "supported": true, "maxResults": 1000 },
  "changePassword": { "supported": false },
  "sort": { "supported": false },
  "etag": { "supported": false },
  "authenticationSchemes": [
    {
      "type": "oauth2",
      "name": "OAuth2 Bearer Token",
      "description": "ES256 JWT issued by POST /oauth/token (client_credentials grant)",
      "specUri": "https://tools.ietf.org/html/rfc6750",
      "primary": true
    }
  ],
  "meta": {
    "resourceType": "ServiceProviderConfig",
    "location": "/scim/v2/ServiceProviderConfig"
  }
}

Related Capabilities

• POST /gtr — Global Token Revocation (RFC 9493). Sets enforcement_mode=deny for the linked operator.
• POST /logout/backchannel — Back-channel session termination. Records the logout event in the provenance ledger.
• GET /.well-known/oauth-authorization-server — Authorization Server Metadata (RFC 8414)
• GET /.well-known/jwks.json — JSON Web Key Set (RFC 7517). EC P-256 public key for token verification.
• GET /entitlements — Operator tier, quota, and balance report (scope: governance:entitlements)

Error Responses

All error responses follow the SCIM error schema (RFC 7644 Section 3.12):

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "404",
  "detail": "User not found"
}

401 Unauthorized

Bearer token missing, expired, or already used (replay)

404 Not Found

User ID does not exist, or POST /Users with a userName that has no matching provisioned operator

400 Bad Request

Malformed SCIM payload or unsupported filter expression