SCIM provisioning

Overview

Use this page to look up inbound SCIM 2.0. SSO still authenticates. SCIM owns organization membership. Related: Provision members with SCIM.

Endpoint

Item	Value
Tenant URL	`{tenant URL}` (copy from Settings → Security → Directory (SCIM))
Auth	Bearer token shown once on generate or rotate
RBAC	`sso.read` / `sso.manage`
Entitlement	Enterprise `scim`, plus at least one enabled, domain-verified SSO provider
Limits	300 requests/minute per IP and normalized request path; 1 MiB request body; `/Bulk` is not supported

Every error uses the SCIM Error schema with a string status and a detail. Bulk requests are not supported.

curl -sS '{tenant URL}/Users' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/scim+json'

GET {tenant URL}/Users
Authorization: Bearer {token}
Accept: application/scim+json

User mapping

Field	What you send
Email	The person’s work email. New access must belong to an enabled provider’s verified domain. An existing organization member can still be linked after a domain change. Otherwise, shipd links an existing account only when its email is verified. Entra placeholder addresses are rejected.
`externalId`	The IdP subject so later SSO can match: Entra `oid`, Okta user id

An active (or decommissioning) SCIM connection disables SSO JIT. SSO looks up externalId from the OIDC sub and, for Entra, the verified oid claim. Inactive, missing, or tombstoned identities are rejected (SCIM_USER_NOT_ACTIVE) unless the person has a manually managed membership. SCIM never rewrites the global profile of an account it linked.

Membership

Directory event	What shipd does
Active user	Creates a SCIM-owned `viewer` membership, or preserves an existing manual membership. Cancels pending invites for that email.
Inactive / removed user	Deletes only a SCIM-owned `viewer` membership, its organization team links, and the user’s existing sessions.
Manual role change	Transfers the membership to manual ownership, so a later directory deactivation does not delete it.
Groups	Stores `POST /Groups` and membership changes deterministically. No group grants a shipd role or creates a product team.

Repeated provisioning does not create duplicate organization memberships.

Audit

Action	Actor
`identity.member.`, `identity.teamMember.`, `identity.scim_membership_ownership.*`	Directory membership reconciliation
`identity.scim_user.`, `identity.scim_group.`, `identity.scim_group_member.*`	SCIM resources and group membership
`identity.scim_managed_connection.`, `identity.scim_managed_credential.`	Connection and credential lifecycle
`scim.connection.created` / `rotated` / `revoked` / `decommissioned`	Dashboard admin lifecycle actions

Directory and connection changes appear in your organization’s audit log. Events can appear shortly after the change; you do not need to repeat a successful provisioning request while waiting for audit history.

Lifecycle

Generate, rotate, and revoke the token on Settings → Security → Directory (SCIM). Tokens are scoped to one connection and organization and are shown only once. Store them securely; rotate a lost token. Revoke and decommission remain available after entitlement loss or SSO-provider disablement. Decommissioning is asynchronous: 202 Accepted includes Location and Retry-After while cleanup continues. Poll after that delay; completion returns 200. Repeated creates and updates do not duplicate resources or memberships. Updates use the resource state that arrives last; SCIM 2.0 does not supply a portable provider sequence number, so an IdP must retry its current authoritative state after delivering requests out of order.

HTTP APIs

Operations APIs

Enterprise APIs

Errors

SCIM provisioning

Overview

Endpoint

User mapping

Membership

Audit

Lifecycle

​Overview

​Endpoint

​User mapping

​Membership

​Audit

​Lifecycle

Overview

Endpoint

User mapping

Membership

Audit

Lifecycle