> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoq.one/llms.txt
> Use this file to discover all available pages before exploring further.
# SCIM 2.0 provisioning for Knoq organizations
> Use SCIM 2.0 to automate user provisioning and deprovisioning for your Knoq organization. Available on the Business plan.
Knoq supports the [SCIM 2.0](https://scim.cloud/) standard, allowing your Identity Provider (IdP) to automatically provision new users, update their profiles, and deprovision them when they leave your organisation — all without manual admin intervention. When a user is deprovisioned via SCIM, Knoq removes their OAuth tokens, agent memory, and organisation membership in a single cascading operation, and the action is recorded in your audit log.
SCIM provisioning is available on the **Business plan** only. If your organisation is on a lower tier, upgrade before attempting to configure a SCIM integration.
## Prerequisites
Before you configure SCIM, make sure the following are in place:
* Your Knoq organisation is on the **Business tier**.
* Enterprise SSO is configured for your organisation. SCIM tokens are issued under your SSO settings, so SSO must be active first. Navigate to **Admin → SSO** to set this up if you haven't already.
* You have **Admin** access to your Knoq organisation and to your Identity Provider's admin console.
## Generate a SCIM token
1. Sign in to Knoq and navigate to **Admin → SSO → SCIM**.
2. Click **Generate Token**.
3. Copy the token immediately — it is shown only once. If you lose it, generate a new one (which invalidates the previous token).
Store the token securely in your IdP's credential vault or secrets manager. You will supply it to your IdP during the setup steps below.
## Base URL
All SCIM requests target:
```
https://knoq.one/api/scim
```
Both path formats are accepted by the Knoq SCIM handler:
```
https://knoq.one/api/scim/Users
https://knoq.one/api/scim/v2/Users
```
## Authentication
Include your SCIM token as a Bearer token in every request:
```
Authorization: Bearer
```
Requests without a valid token receive a `401 Unauthorized` response.
## Supported operations
| Resource | Operation | Method | Path |
| -------- | ------------------------ | -------- | ---------------------- |
| Users | Provision (create) | `POST` | `/api/scim/Users` |
| Users | Read (single user) | `GET` | `/api/scim/Users/{id}` |
| Users | List all users | `GET` | `/api/scim/Users` |
| Users | Update profile | `PUT` | `/api/scim/Users/{id}` |
| Users | Deactivate (deprovision) | `PATCH` | `/api/scim/Users/{id}` |
| Users | Delete | `DELETE` | `/api/scim/Users/{id}` |
| Groups | List | `GET` | `/api/scim/Groups` |
When you send a `PATCH` or `PUT` request with `"active": false`, Knoq treats it as a full deprovision: OAuth tokens, agent memory, member profile, and the organisation membership are all deleted, and the member is removed from your organisation.
## Example: provision a user
The following request creates a new user in your Knoq organisation. The user receives a `viewer` role by default and can be promoted to `admin` from the Knoq Admin panel.
```bash curl theme={null}
curl -X POST https://knoq.one/api/scim/Users \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "ada.lovelace@example.com",
"name": {
"formatted": "Ada Lovelace",
"givenName": "Ada",
"familyName": "Lovelace"
},
"emails": [
{
"value": "ada.lovelace@example.com",
"primary": true
}
],
"active": true
}'
```
```json Response theme={null}
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "member_01HZ9K2XR3S4T5U6V7W8X9Y0Z1",
"userName": "ada.lovelace@example.com",
"name": {
"formatted": "Ada Lovelace"
},
"emails": [
{
"value": "ada.lovelace@example.com",
"primary": true
}
],
"active": true
}
```
### Example: deprovision a user
Send a `PATCH` request with `"active": false` to remove a user from your organisation:
```bash curl theme={null}
curl -X PATCH \
"https://knoq.one/api/scim/Users/member_01HZ9K2XR3S4T5U6V7W8X9Y0Z1" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op": "replace",
"value": {
"active": false
}
}
]
}'
```
```json Response theme={null}
HTTP 204 No Content
```
## IdP setup guides
### Okta
1. In the Okta Admin Console, go to **Applications → Applications** and create a new app integration using the **SCIM 2.0** template (or select your existing Knoq SAML app if you have one, and enable SCIM provisioning on its **Provisioning** tab).
2. Set the **SCIM connector base URL** to `https://knoq.one/api/scim`.
3. Set the **Unique identifier field for users** to `userName`.
4. Under **Authentication Mode**, select **HTTP Header** and paste your Knoq SCIM token.
5. Enable **Push New Users**, **Push Profile Updates**, and **Push User Deactivation**.
6. Assign the Knoq app to the groups or users you want to provision.
Refer to [Okta's SCIM provisioning documentation](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_scim.htm) for full configuration details.
### Microsoft Entra ID (Azure AD)
1. In the [Microsoft Entra admin center](https://entra.microsoft.com), navigate to **Enterprise applications** and open your Knoq application (or create a new non-gallery app).
2. Go to **Provisioning** and set the **Provisioning Mode** to **Automatic**.
3. Under **Admin Credentials**, set the **Tenant URL** to `https://knoq.one/api/scim` and paste your Knoq SCIM token in the **Secret Token** field.
4. Click **Test Connection** to verify the credentials.
5. Under **Mappings**, confirm that `userPrincipalName` maps to `userName`.
6. Save and set the **Provisioning Status** to **On**.
Refer to [Microsoft's tutorial on configuring automatic user provisioning](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/configure-automatic-user-provisioning-portal) for full details.