---
title: SCIM API
description: 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.
section: cloud
order: 400
audience: [operator, builder]
sources: [services/nodejs-cloud/app/scim/v2, services/nodejs-cloud/lib/scim, services/nodejs-cloud/lib/sso/settings.ts, services/nodejs-cloud/lib/sso/members.ts, docs/cloud-sso.md]
features: [cloud.scim]
---

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 {#setup}

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:

```bash
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 {#create-user}

```bash
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
  }'
```

```python
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 {#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 {#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}

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 {#patch}

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

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

```json
{"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 {#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}

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

```json
{"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 {#related}

- [Venom Cloud APIs overview](/docs/cloud/api-overview.md#credentials) for the other credentials.
- [Sign-in flows](/docs/cloud/api-auth-flows.md#sso) for the SSO URLs the IdP needs.
- [Single sign-on](/docs/cloud/console-sso.md) for the console's settings and IdP walkthroughs.
