Skip to main content

SCIM 2.0 Provisioning

KnoxCall implements RFC 7644 (SCIM Protocol) and RFC 7643 (SCIM Schema) so your identity provider can create, update and deprovision workspace members — and OAuth clients — without anyone logging into KnoxCall. This is the page your connector’s documentationUri points at. If you arrived here from GET /scim/v2/ServiceProviderConfig, you are in the right place.
SCIM provisioning requires the Pro or Enterprise plan. Discovery (/ServiceProviderConfig, /Schemas, /ResourceTypes) is served on every plan so that a connector can be configured and can read this URL; the /Users and /OAuthClients endpoints are served to workspaces whose plan includes SCIM. See Plan requirement for exactly what a workspace sees when the plan does not cover it.

Base URL

The SCIM service lives under /scim/v2 on your workspace’s KnoxCall control-plane host:
https://admin.knoxcall.com/scim/v2 works too. Requests that arrive on any other hostname — including directly to the origin address — are answered 404 before authentication is attempted, so paste the workspace URL exactly. Every endpoint is relative to that base:

Groups

A group is a list of people your identity provider maintains. A group grants no role and no access: joining or leaving one changes nothing about what that person can do in KnoxCall.
  • A members value is the id of a /Users resource in this workspace. An id nothing resolves is 400 invalidValue, and the whole request is refused.
  • displayName is unique within the workspace, ignoring case. A duplicate is 409 uniqueness.
  • Reads honour excludedAttributes=members and attributes.
  • A successful PATCH answers 204 with no body.
  • Removing someone who is already out of the group succeeds and changes nothing, so a retry never reads as a failure.
  • A PUT that omits members leaves them as they are. members: [] empties the group.
  • A person whose /Users resource was deleted no longer appears in members.
  • Only a Live credential can use /Groups, because a workspace has one directory.
  • Filter membership with members[value eq "<id>"] or members.value eq "<id>". A bare members eq "<id>" matches nothing.
  • Nested groups are not supported.
Deleting a group also removes it from any AI-gateway directory entry billed to it.

Token issuance

Your connector authenticates with a SCIM credential — a bearer token that begins with scim_. It is not a user’s session and not an API key; it belongs to the workspace, carries its own tenant binding, and reaches /scim/v2 and nothing else. To issue one, an owner or admin opens Provisioning (SCIM) in the KnoxCall dashboard (/settings/scim, linked from Settings → Security beside Single sign-on, or search “SCIM” in the command palette) and chooses New credential (POST /admin/scim/credentials if you are scripting it). The same page shows your workspace’s base URL with a copy button, lists every credential with when it was last used and when it expires, revokes them, and carries the setup steps for Entra ID, Okta and other SCIM 2.0 clients. Minting requires a recent second-factor step-up made with "action_scope": "scim.credential" (an emailed code does not count), is written to the audit log, and asks for an explicit expiry — a credential with no expiry is something you have to choose, never something you get by omitting a field. On a workspace whose plan does not include SCIM, New credential explains what is required instead of offering a form the server would refuse. Listing and revoking work on every plan.

What a credential can provision

Each credential is minted for people and groups, OAuth clients, or both, and reaches only what it was minted for: A credential for an identity provider such as Entra ID or Okta needs people and groups only, and that is what a new Live credential gets unless you tick OAuth clients too. In the API, send "capabilities": ["directory"], ["oauth_clients"] or both; leave it out and a Live credential gets ["directory"]. A Test credential can hold OAuth clients only, because people and groups are not split into Live and Test, and leaving the field out gives it ["oauth_clients"]. An empty, unknown or malformed list is refused with a 400 (invalid_capabilities), and nothing is minted. Credentials created before capabilities existed keep both. A request to a resource the credential cannot provision is refused with a 403 SCIM Error whose error is scim_capability_required, and nothing is changed. Discovery is never refused, and it describes the credential: /ResourceTypes and /Schemas list only the resource types the credential can provision, so a connector never tries an endpoint it will be refused on.
The token is shown exactly once, when it is minted. It is stored only as a SHA-256 digest, so it cannot be recovered — if it is lost, revoke it and mint another.
Use a Live credential for /Users. Workspace membership is not partitioned into Live and Test data spaces — a workspace has one set of people — so a Test credential is refused on /Users with a 403. A Test credential does provision /OAuthClients, which is partitioned.
Revoking a credential takes effect on the connector’s next request: the check is a single indexed lookup evaluated against the database clock, not a cache.

Content type

RFC 7644 §3.1 requires application/scim+json, and KnoxCall accepts it on requests and returns it on responses. application/json is accepted on requests as well, so a connector that sends the plain type is not broken by it.

Supported resources

/Users

A User is a workspace membership plus a directory record. The attributes your IdP asserts live on the directory record, never on the person’s global KnoxCall account — one workspace’s directory must not rename or re-address someone in another workspace. active being derived is the property that matters most in practice: if an administrator removes someone from the workspace on the team page, your next GET reports active: false without KnoxCall having to write anything. Provisioning a new person requires a verified domain. SCIM grants membership without asking the subject to accept an invitation, so KnoxCall applies the same admission rule as SAML just-in-time provisioning: the address must sit within a domain this workspace has proven by DNS. Verify the domain under Settings → Single sign-on first. Someone who is already a member can be given a directory record without this. New memberships are always granted at the member role. A SCIM connector cannot mint an administrator.

Deprovisioning

Both forms end the membership immediately, and neither erases personal data — erasure is a separate, subject-initiated process:
  • PATCH with active: false — the membership is revoked and the directory record stays, so a later GET returns it with active: false. This is the shape Entra sends on a soft-delete.
  • DELETE — the same revocation, plus a tombstone on the directory record, so a later GET returns 404.
A deprovision always wins over a rename in the same request. Entra sometimes sends active: false together with a new userName (for example a leaver’s renamed UPN). KnoxCall ends the membership first, so that no other change in the request can block an offboarding. If the new userName or externalId already belongs to another person in the workspace, that directory change cannot be stored. KnoxCall then answers 200 with the resource as it now stands: active: false and the old userName. The audit log records which attributes were not written (columns_not_written). This knowingly departs from RFC 7644 §3.5.2, which treats a multi-operation PATCH as all-or-nothing. All-or-nothing would mean either restoring the person’s access or answering an error after their access had already ended, and Entra would then retry an offboarding that is already done, forever. If your provisioning log shows a successful deactivation but the name did not change, this is why. Resolve the userName clash in your directory, and the next update carries the rename. The same applies to a PUT carrying active: false. A rename that collides without a deprovision still answers 409 uniqueness and changes nothing. A former member’s account is no longer projected. While someone is a member, a User that your directory has not given an email or a name falls back to their KnoxCall account’s address and name. Once their access ends, the resource shows only what your directory asserted (userName, externalId, the name fields, the work email). Any later change the person makes to their own KnoxCall account, which they may use at other workspaces, never reaches your connector.

/OAuthClients

A custom resource, urn:knoxcall:scim:2.0:OAuthClient, for provisioning machine credentials alongside people. Only a credential minted with the OAuth clients capability can use it (see What a credential can provision). clientName, allowedScopes, redirectUris, requirePkce, requireDpop, stepUpScopes and active are writable; clientId, clientType and grantTypes are not. The client_secret of a confidential client is returned exactly once, on create. Redirect URIs are validated on registration with the same rule the dashboard and the Management API apply — a non-registrable URI is refused with a 400 rather than silently dropped from the list. grantTypes accepts client_credentials, authorization_code, refresh_token, urn:ietf:params:oauth:grant-type:token-exchange and urn:ietf:params:oauth:grant-type:device_code, and defaults to ["client_credentials"] when omitted. Any other value is refused with 400 invalidValue, and nothing is created. It is never dropped from the list. A clientId is tk_ followed by 32 hexadecimal characters (128 bits). Clients created before 2026-11 have shorter ids, and those keep working. A revoked client is a deleted resource. DELETE /OAuthClients/{id} revokes the client and its tokens, and revocation is permanent. Afterwards, as RFC 7644 §3.6 requires, GET, PUT and PATCH on that id answer 404, and the client no longer appears in GET /OAuthClients. That includes a client revoked from the dashboard or the Management API. No request can make a revoked client active again. Create a new one instead.

Filtering

filter implements the RFC 7644 §3.4.2.2 grammar, not a subset of it:
  • Comparison operators eq, ne, co, sw, ew, gt, ge, lt, le, and the presence operator pr
  • and, or, not, and parentheses
  • Value filters on multi-valued attributes — emails[type eq "work"]
  • URN-qualified attribute names
Attribute names are matched case-insensitively, as RFC 7643 §2.1 requires, except for the identifiers id, externalId and clientId, which RFC 7643 §7 defines as case-exact. userName deliberately folds case, so userName eq "Ada@Example.com" finds the record stored as ada@example.com. A filter KnoxCall cannot honour is answered 400 with scimType: "invalidFilter" — it is never ignored, and you will never receive an unfiltered list in response to a filter we did not understand. Pagination is startIndex (1-based) and count, capped at the filter.maxResults value /ServiceProviderConfig advertises. itemsPerPage is the number of resources on the page you received, and totalResults counts everything that matched the filter. A filter that matches nothing is an empty list (totalResults: 0), never a 404.

Attributes accepted but not stored

Entra’s default user mapping sends attributes KnoxCall has no home for. Rejecting them would refuse the whole PatchOp — including the active: false in the same request — so an offboarding would silently not happen. KnoxCall therefore accepts these, names them in the audit record, and stores none of them: Anything outside that set — an unknown core attribute, a custom extension, a foreign schema URN — is still refused with scimType: "invalidPath", and the schema qualifier on a path is read, so urn:…:enterprise:2.0:User:active does not deactivate anyone.

Plan requirement

SCIM provisioning is included on the Pro and Enterprise plans, alongside single sign-on. Free and Starter do not include it. Discovery is never gated. /ServiceProviderConfig, /Schemas and /ResourceTypes answer on every plan, so a connector can always be configured and can always read this page’s URL out of the capability document. The resource endpoints are. A workspace whose plan does not include SCIM receives 403 on /Users and /OAuthClients with a SCIM Error object:
The error member is a KnoxCall extension, because RFC 7644 §3.12’s scimType vocabulary is closed and has no value meaning “your plan does not include this”. A SCIM client ignores the extra member; schemas, status and detail are exactly what the RFC specifies. There is no scimType on this refusal — giving it a near-miss value would make a connector retry with a different body forever.

What happens if the subscription lapses

Nothing stops. A workspace on Pro or Enterprise whose subscription goes past_due, enters dunning or is cancelled keeps being provisioned. An identity provider does not read a 403 as “the invoice is unpaid” — Entra marks the object in error, retries, and eventually quarantines the whole provisioning job, and restarting a quarantined job re-runs a full reconciliation. Turning a card decline into that would churn every member of the workspace at the moment the people who could fix the card are the ones losing access. What a lapse does stop is issuing a new SCIM credential. Minting requires a current plan that includes SCIM; connectors that already hold one keep working. A workspace that deliberately downgrades to a lower tier is a different case — that is a choice, not an accident of billing — and its resource endpoints are refused as above. Listing and revoking credentials is never gated. A workspace that has stopped paying must still be able to see which connectors hold a credential and switch them off.

Rate limits

An identity provider does not send traffic like a person. Entra reconciles in bursts, retries aggressively, and treats a 429 without a Retry-After header as a hard failure rather than as backpressure. KnoxCall’s limits are built around that. The unit is the workspace deliberately. Entra’s provisioning service egresses from a shared Azure address pool, so two KnoxCall customers’ reconciliations routinely arrive from the same IP; a purely per-address budget would let one customer’s initial sync throttle another’s connector. A separate per-address flood shield still sits in front of the mount, set above the per-workspace budget so that one workspace can never consume it on its own. A 429 body is a SCIM Error object like any other refusal:
Honour Retry-After. A provisioning cycle interrupted by a 429 can be resumed without losing state — nothing was half-applied, because the request was shed before it reached a handler. At 750 requests per minute a full first-time synchronisation of 10,000 users completes in about fifteen minutes, and an incremental cycle never approaches the ceiling.

Error codes

Every error from /scim/v2 is an RFC 7644 §3.12 Error object, labelled application/scim+json. That covers authentication failures, refusals, unknown paths, unreadable bodies and server faults alike. status is a string, and scimType is present where RFC 7644 defines one:
The one response that is not an Error object is for a request sent to a hostname that is not a KnoxCall control-plane host: that is answered 404 with an empty body before anything else happens (see Base URL).

Authentication errors

A request without a usable credential gets a 401, as RFC 7644 §3.12 defines it (“the authorization header is invalid or missing”), with a WWW-Authenticate challenge (RFC 6750 §3):
That covers a missing Authorization header, a scheme other than Bearer (for example Basic), and Bearer with an empty token. A token that is presented and refused — a scim_ token that is unknown, revoked or expired — is also a 401, and its challenge adds error="invalid_token":
The scim_… token goes in the header exactly as Authorization: Bearer scim_…. Alongside the RFC 7644 §3.12 members, KnoxCall refusals that the scimType vocabulary cannot express carry an error member: A refusal never states whether some other workspace exists. Your credential binds the request to one workspace, so there is nothing to disambiguate.

Setting up Microsoft Entra ID

  1. Create a SCIM credential in KnoxCall (Provisioning (SCIM) → New credential) and copy the scim_… token. It is shown once.
  2. In Entra, open your enterprise application → Provisioning → Automatic.
  3. Tenant URL: https://<workspace>.knoxcall.com/scim/v2
  4. Secret Token: the scim_… token.
  5. Test Connection — Entra fetches /ServiceProviderConfig and /Schemas.
  6. Leave the default user attribute mapping as it is. The attributes KnoxCall does not store are accepted rather than refused, precisely so that the default mapping works unmodified.
  7. Verify your email domain in KnoxCall before starting the first cycle, or every create for a new person is refused.

Setting up Okta

  1. Create a SCIM credential in KnoxCall (Provisioning (SCIM) → New credential) and copy the scim_… token.
  2. In the Okta Admin Console, open your KnoxCall app integration. On its General tab, under App Settings, set Provisioning to SCIM and save.
  3. Provisioning → Integration → Edit.
  4. SCIM connector base URL: https://<workspace>.knoxcall.com/scim/v2
  5. Unique identifier field for users: userName
  6. Supported provisioning actions: Import New Users and Profile Updates, Push New Users and Push Profile Updates (add Push Groups to send groups).
  7. Authentication Mode: HTTP Header, with the scim_… token as the Bearer token under Authorization. Not OAuth 2: KnoxCall issues the token, so there is no authorization server for Okta to call.
  8. Test Connector Configuration, then Save. Under Provisioning → To App, enable Create Users, Update User Attributes and Deactivate Users.
As with Entra, verify your email domain in KnoxCall before the first import or push.

What KnoxCall does not implement

/ServiceProviderConfig is the authoritative answer, and it says so honestly:
  • Bulk operations — not supported
  • Sorting — not supported
  • ETags — not supported
  • changePassword — not supported, and never will be: KnoxCall does not hold member passwords