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’sdocumentationUri 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
membersvalue is theidof a/Usersresource in this workspace. An id nothing resolves is400 invalidValue, and the whole request is refused. displayNameis unique within the workspace, ignoring case. A duplicate is409 uniqueness.- Reads honour
excludedAttributes=membersandattributes. - A successful
PATCHanswers204with no body. - Removing someone who is already out of the group succeeds and changes nothing, so a retry never reads as a failure.
- A
PUTthat omitsmembersleaves them as they are.members: []empties the group. - A person whose
/Usersresource was deleted no longer appears inmembers. - Only a Live credential can use
/Groups, because a workspace has one directory. - Filter membership with
members[value eq "<id>"]ormembers.value eq "<id>". A baremembers eq "<id>"matches nothing. - Nested groups are not supported.
Token issuance
Your connector authenticates with a SCIM credential — a bearer token that begins withscim_. 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.
Content type
RFC 7644 §3.1 requiresapplication/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:PATCHwithactive: false— the membership is revoked and the directory record stays, so a laterGETreturns it withactive: false. This is the shape Entra sends on a soft-delete.DELETE— the same revocation, plus a tombstone on the directory record, so a laterGETreturns404.
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 operatorpr and,or,not, and parentheses- Value filters on multi-valued attributes —
emails[type eq "work"] - URN-qualified attribute names
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 wholePatchOp — 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:
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 goespast_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 a429 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:
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 a401, as RFC 7644 §3.12 defines it (“the
authorization header is invalid or missing”), with a WWW-Authenticate challenge (RFC 6750 §3):
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":
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
- Create a SCIM credential in KnoxCall (Provisioning (SCIM) → New credential) and copy
the
scim_…token. It is shown once. - In Entra, open your enterprise application → Provisioning → Automatic.
- Tenant URL:
https://<workspace>.knoxcall.com/scim/v2 - Secret Token: the
scim_…token. - Test Connection — Entra fetches
/ServiceProviderConfigand/Schemas. - 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.
- Verify your email domain in KnoxCall before starting the first cycle, or every create for a new person is refused.
Setting up Okta
- Create a SCIM credential in KnoxCall (Provisioning (SCIM) → New credential) and copy
the
scim_…token. - In the Okta Admin Console, open your KnoxCall app integration. On its General tab, under App Settings, set Provisioning to SCIM and save.
- Provisioning → Integration → Edit.
- SCIM connector base URL:
https://<workspace>.knoxcall.com/scim/v2 - Unique identifier field for users:
userName - Supported provisioning actions: Import New Users and Profile Updates, Push New Users and Push Profile Updates (add Push Groups to send groups).
- 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. - Test Connector Configuration, then Save. Under Provisioning → To App, enable Create Users, Update User Attributes and Deactivate Users.
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