Skip to content
Docs menu

SCIM API

Provision and deprovision your org's members from Okta, Entra ID or any SCIM 2.0 client through /scim/v2, with group-to-role mapping.

View .md

Venom Cloud speaks SCIM 2.0 (RFC 7643 and 7644) so your identity provider can create, update and remove org members on its own. A SCIM user is an org member while it is active. Its groups decide its role through the group rules you set up with single sign-on. Okta and Microsoft Entra ID work out of the box; any client that sends standard SCIM requests works too.

Set it up

  1. In the console, Settings, Single sign-on: connect your IdP (OIDC or SAML) and add group rules. An org owner does this (sso:manage).
  2. Create a SCIM token there. It is shown once and looks like vsc_…. An org can hold at most 5 live tokens; rotate one to replace it.
  3. In the IdP, set the SCIM base URL to https://cloud.usevenom.dev/scim/v2 (your own origin when self-hosted) and the token as the bearer token. Okta: "Unique identifier field for users" is userName.

Check the token:

export SCIM_TOKEN=vsc_...
curl -s https://cloud.usevenom.dev/scim/v2/ServiceProviderConfig \
  -H "Authorization: Bearer $SCIM_TOKEN"

The token fixes the org. One org's token never sees another org's users or groups: they answer 404.

Provision a user

curl -s https://cloud.usevenom.dev/scim/v2/Users \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "ada@example.com",
    "name": {"givenName": "Ada", "familyName": "Lovelace"},
    "emails": [{"value": "ada@example.com", "type": "work", "primary": true}],
    "active": true
  }'
import os, requests

base = "https://cloud.usevenom.dev/scim/v2"
h = {"Authorization": f"Bearer {os.environ['SCIM_TOKEN']}", "Content-Type": "application/scim+json"}

# Find a user by userName, then deactivate it.
found = requests.get(f"{base}/Users", headers=h, params={"filter": 'userName eq "ada@example.com"'}).json()
uid = found["Resources"][0]["id"]
requests.patch(f"{base}/Users/{uid}", headers=h, json={
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{"op": "replace", "path": "active", "value": False}],
}).raise_for_status()

What creating a user does:

  • If an org member already has that email (someone who signed up through the console), the SCIM user is linked to them: they keep their id, role and keys.
  • Otherwise a new member is made with the connection's default role. The plan's member limit applies.
  • The user needs an email: emails, or a userName that is an email address.

Routes

All routes take Authorization: Bearer vsc_… and answer application/scim+json.

Route What it does
GET /scim/v2/ServiceProviderConfig what is supported: PATCH yes, bulk no, filter yes (up to 200 results), sort no, ETags yes, change password no
GET /scim/v2/ResourceTypes User and Group
GET /scim/v2/Schemas the User and Group attributes Venom keeps
GET /scim/v2/Users list users; filter, startIndex, count, excludedAttributes=groups
POST /scim/v2/Users create a user (201, with ETag and Location)
GET /scim/v2/Users/{id} one user, with its groups
PUT /scim/v2/Users/{id} replace a user; a missing active keeps the current value
PATCH /scim/v2/Users/{id} change attributes with a PatchOp
DELETE /scim/v2/Users/{id} deprovision the member and forget the SCIM user (204)
GET /scim/v2/Groups list groups; filter, startIndex, count, excludedAttributes=members
POST /scim/v2/Groups create a group with displayName and optional members
GET /scim/v2/Groups/{id} one group with its members
PUT /scim/v2/Groups/{id} replace a group (name and members)
PATCH /scim/v2/Groups/{id} add, replace or remove members, rename
DELETE /scim/v2/Groups/{id} delete a group; its former members' roles are recomputed (204)

Attributes

Resource Attribute Notes
User userName required, unique in the org (case-insensitive)
User externalId the IdP's id, case-exact
User displayName, name.givenName, name.familyName optional
User emails one work email is kept; a user always keeps an email
User active false deprovisions, true re-adds
User groups read-only: value, display, $ref
Group displayName required, unique in the org
Group externalId optional
Group members [{"value": "<user id>"}]; every member must be a SCIM user of this org

Attributes Venom does not keep (title, phone numbers, the enterprise extension) are accepted and ignored. Every resource has meta.version, a weak ETag (W/"3") that changes with each write.

Filters and paging

Filters are the subset IdPs send: one or more <attribute> eq <value> joined by and, where the value is a JSON string or a boolean.

Resource Filterable attributes
User userName, externalId, id, emails.value (also emails[type eq "work"].value), displayName, active
Group displayName, externalId, id

Anything else (or, not, other operators, grouping, a filter over 1,000 characters) is 400 with scimType: invalidFilter.

Paging is RFC 7644's: startIndex is 1-based (default 1) and count defaults to 100, at most 200. The list answer is a ListResponse with totalResults, startIndex, itemsPerPage and Resources.

PATCH

A PatchOp body has 1 to 100 Operations. Ops are case-insensitive and both IdP styles work:

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

For groups, add, replace and remove take a members path, and remove also takes members[value eq "<user id>"]. remove always needs a path.

Roles, owners and deprovisioning

  • A user's role is the first group rule that matches one of its groups, else the connection's default role. A group change recomputes the role of every user it touches.
  • SCIM never makes, changes, deprovisions or re-emails an owner. Deprovisioning an owner answers 409 with scimType: mutability; remove owners in the console.
  • active: false or DELETE removes the member. Their console sessions end on their next request. Their client keys follow the org's key policy (deprovision_keys): revoke (default), pause or keep. CLI logins they approved but nobody picked up yet are denied. Signing in through the IdP is refused while the user is inactive.
  • active: true again makes them a member with the role their groups map to. Revoked keys stay revoked.

Every SCIM call, reads included, writes an audit row with the actor scim:<token id> (scim.user_created, scim.user_patched, scim.group_listed, …). Deprovisioning also writes member.deprovisioned.

Errors

Errors use the SCIM error shape, not the OpenAI one:

{"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "status": "409", "scimType": "uniqueness", "detail": "userName ada@example.com is already provisioned in this organisation."}
Status scimType When
400 invalidSyntax, invalidFilter, invalidValue, invalidPath, noTarget, mutability a bad body, filter, value or path; removing userName, active or the email
401 missing or unknown token (WWW-Authenticate: Bearer realm="scim")
404 no such user or group in this org
409 uniqueness, mutability a taken userName, email or displayName; an owner
413 a body over 1 MiB