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.
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
- In the console, Settings, Single sign-on: connect your IdP (OIDC or SAML) and add group rules. An org
owner does this (
sso:manage). - 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. - 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" isuserName.
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 auserNamethat 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
409withscimType: mutability; remove owners in the console. active: falseorDELETEremoves the member. Their console sessions end on their next request. Their client keys follow the org's key policy (deprovision_keys):revoke(default),pauseorkeep. CLI logins they approved but nobody picked up yet are denied. Signing in through the IdP is refused while the user is inactive.active: trueagain 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 |
Related
- Venom Cloud APIs overview for the other credentials.
- Sign-in flows for the SSO URLs the IdP needs.
- Single sign-on for the console's settings and IdP walkthroughs.