SCIM Provisioning API

Qarion exposes a SCIM v2 endpoint for automated user lifecycle management via your Identity Provider (IdP). This enables real-time synchronization of user status from Okta, Azure AD, OneLogin, or any SCIM 2.0 client.

SCIM endpoints use bearer token authentication — not the standard JWT auth used by other API routes. Set the SCIM_BEARER_TOKEN environment variable to enable provisioning.

Endpoints Overview

Method	Endpoint	Description
GET	/scim/v2/Users	List or search users
GET	/scim/v2/Users/{user_id}	Get a single user
POST	/scim/v2/Users	Provision a new user
PUT	/scim/v2/Users/{user_id}	Full replacement of a user
PATCH	/scim/v2/Users/{user_id}	Partial update (e.g., deactivate)
DELETE	/scim/v2/Users/{user_id}	Soft-delete (deactivate) a user

---

Authentication

All SCIM endpoints require a bearer token in the Authorization header:

Authorization: Bearer <SCIM_BEARER_TOKEN>

Status	Condition
401	Token missing, malformed, or invalid
501	SCIM_BEARER_TOKEN not configured on the server

---

List Users

GET /scim/v2/Users?filter=userName eq "alice@example.com"&startIndex=1&count=100

Parameter	Type	Default	Description
filter	string	—	SCIM filter expression (supports userName eq "value")
startIndex	integer	1	1-indexed pagination start
count	integer	100	Max results per page

Response

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "startIndex": 1,
  "itemsPerPage": 100,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "uuid",
      "userName": "alice@example.com",
      "name": { "givenName": "Alice", "familyName": "Smith" },
      "emails": [{ "value": "alice@example.com", "primary": true }],
      "active": true,
      "meta": { "resourceType": "User" }
    }
  ]
}

---

Get User

GET /scim/v2/Users/{user_id}

Returns a single SCIM User resource. Returns 404 if not found.

---

Create User

POST /scim/v2/Users

Request Body

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "bob@example.com",
  "name": { "givenName": "Bob", "familyName": "Jones" },
  "active": true
}

Field	Type	Required	Description
userName	string	✅	User's email address
name.givenName	string	—	First name
name.familyName	string	—	Last name
active	boolean	—	Defaults to true

Behavior

• If a user with the same email already exists and is inactive, they are reactivated (not duplicated).
• If a user with the same email already exists and is active, their profile fields are updated.
• SCIM-provisioned users cannot log in with a password — they must authenticate via SSO.

Returns: 201 Created with the SCIM User resource.

---

Replace User (PUT)

PUT /scim/v2/Users/{user_id}

Full replacement of user attributes. If active is set to false, this triggers user deactivation and auto-revocation of all active product access (see Auto-Revoke).

---

Patch User (PATCH)

PATCH /scim/v2/Users/{user_id}

Request Body

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

The most common SCIM PATCH operation is deactivating a user when they leave the organization. This is the primary mechanism for IdP-triggered access revocation.

---

Delete User (Soft-Delete)

DELETE /scim/v2/Users/{user_id}

Soft-deletes (deactivates) the user. Does not permanently remove the user from the database.

Returns: 204 No Content

---

Auto-Revoke on Deactivation

When a user is deactivated via any SCIM operation (PUT, PATCH, or DELETE), the following happens automatically:

1. User deactivated — is_active = false, deactivation_source = "scim"
2. All active product access revoked — every ProductAccess row for the user is set to is_active = false with revocation_reason = "auto_departed"
3. Audit trail entries — one access.auto_revoked audit event per revoked grant
4. Webhook dispatch — access.auto_revoked events sent to subscribed webhooks in each affected space

This ensures that when an employee is deprovisioned in your IdP, their data access is immediately revoked across all spaces — without waiting for the next recertification cycle.

---

Configuration

Environment Variable	Required	Description
SCIM_BEARER_TOKEN	Yes	Static bearer token for IdP authentication

[!WARNING] If SCIM_BEARER_TOKEN is not set, all SCIM endpoints return 501 Not Implemented.

IdP Setup Guides

Okta

1. In Okta Admin Console, go to Applications → Add Application → SCIM 2.0 Test App
2. Set the SCIM base URL to https://your-qarion-instance.com/scim/v2
3. Set the authentication mode to HTTP Header and paste your SCIM_BEARER_TOKEN
4. Enable provisioning: Create Users, Update User Attributes, Deactivate Users

Azure AD

1. In Azure Portal, go to Enterprise Applications → Your App → Provisioning
2. Set provisioning mode to Automatic
3. Set the Tenant URL to https://your-qarion-instance.com/scim/v2
4. Set the Secret Token to your SCIM_BEARER_TOKEN
5. Test connection and start provisioning