SCIM User Provisioning
Create, update and deactivate administrators automatically from your identity provider (SCIM 2.0).
Prerequisites
- An API key with the required scopes
- An active PlanDocket account
Enable SCIM and Create a Token
In the admin area, open your identity provider under Settings > SSO, enable SCIM provisioning and generate a bearer token. In your identity provider (e.g. Microsoft Entra ID, Okta), enter the SCIM base URL https://your-tenant.plandocket.com/scim/v2 and this token. Every request needs the header "Authorization: Bearer <token>"; responses use the content type application/scim+json. Keep the token safe: it grants write access to administrator accounts.
Check the Connection (Discovery)
The discovery endpoints ServiceProviderConfig, Schemas and ResourceTypes describe the supported features: PATCH and filtering are supported (max. 100 results per page, paginated with startIndex and count); bulk, sorting, ETags and password changes are not.
curl -X GET "https://your-tenant.plandocket.com/scim/v2/ServiceProviderConfig" \
-H "Authorization: Bearer YOUR_SCIM_TOKEN" \
-H "Accept: application/scim+json"Create Users
POST /scim/v2/Users creates an administrator. userName (the email address) is required, and the email domain must be allowed for the identity provider. An existing SSO-only account with the same email address is linked instead of duplicated; a local password account or an account that is already provisioned via SCIM is rejected with 409 (uniqueness). If your plan's maximum number of administrators has been reached, it responds with 403.
curl -X POST "https://your-tenant.plandocket.com/scim/v2/Users" \
-H "Authorization: Bearer YOUR_SCIM_TOKEN" \
-H "Content-Type: application/scim+json" \
-d '{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"externalId": "00u1abcd",
"userName": "max.mustermann@acme.example",
"name": {"givenName": "Max", "familyName": "Mustermann"},
"emails": [{"value": "max.mustermann@acme.example", "primary": true}],
"active": true
}'Find Users
GET /scim/v2/Users supports the filters "userName" / "emails.value" with eq, co, sw or ew, plus "externalId eq" and "id eq". Other filters are rejected with 400 (invalidFilter).
curl -G "https://your-tenant.plandocket.com/scim/v2/Users" \
-H "Authorization: Bearer YOUR_SCIM_TOKEN" \
--data-urlencode 'filter=userName eq "max.mustermann@acme.example"' \
--data-urlencode 'startIndex=1' \
--data-urlencode 'count=25'Update or Deactivate Users
PATCH /scim/v2/Users/{id} supports the operations add, replace and remove; PUT replaces the user completely. "active": false deactivates the account and ends running sessions. DELETE does not delete the account but deactivates it, so audit history and ownership are kept; afterwards the SCIM user can no longer be retrieved (404). Super admin accounts are protected and cannot be modified or deactivated via SCIM.
curl -X PATCH "https://your-tenant.plandocket.com/scim/v2/Users/SCIM_USER_ID" \
-H "Authorization: Bearer YOUR_SCIM_TOKEN" \
-H "Content-Type: application/scim+json" \
-d '{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{"op": "replace", "path": "active", "value": false}
]
}'Groups and Roles
Groups are provisioned via /scim/v2/Groups (filters: "displayName eq", "externalId eq", "id eq"). Map PlanDocket roles to groups in the SSO provider settings: members get the role of their mapped group, users without a mapped group get the provider's default role. When a user is removed from all mapped groups, or the group is deleted, they fall back to the default role. The super admin role is never assigned via SCIM.
curl -X POST "https://your-tenant.plandocket.com/scim/v2/Groups" \
-H "Authorization: Bearer YOUR_SCIM_TOKEN" \
-H "Content-Type: application/scim+json" \
-d '{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "PlanDocket Editors",
"members": [{"value": "SCIM_USER_ID"}]
}'