Skip to main content
Knoq supports the SCIM 2.0 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 <your-scim-token>
Requests without a valid token receive a 401 Unauthorized response.

​
Supported operations

ResourceOperationMethodPath
UsersProvision (create)POST/api/scim/Users
UsersRead (single user)GET/api/scim/Users/{id}
UsersList all usersGET/api/scim/Users
UsersUpdate profilePUT/api/scim/Users/{id}
UsersDeactivate (deprovision)PATCH/api/scim/Users/{id}
UsersDeleteDELETE/api/scim/Users/{id}
GroupsListGET/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. 
curl -X POST https://knoq.one/api/scim/Users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-scim-token>" \
  -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
  }'

​
Example: deprovision a user

Send a PATCH request with "active": false to remove a user from your organisation: 
curl -X PATCH \
  "https://knoq.one/api/scim/Users/member_01HZ9K2XR3S4T5U6V7W8X9Y0Z1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-scim-token>" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "value": {
          "active": false
        }
      }
    ]
  }'

​
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 for full configuration details.

​
Microsoft Entra ID (Azure AD)

  1. In the Microsoft Entra admin center, 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 for full details.