> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useshipd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM provisioning

> Tenant URL, bearer auth, externalId mapping, membership rules, and audit actions.

## Overview

Use this page to look up inbound SCIM 2.0. SSO still authenticates. SCIM owns organization membership.

Related: [Provision members with SCIM](/enterprise/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.

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

```http HTTP theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.