Writer SCIM API guide

Writer supports SCIM 2.0 provisioning of users and groups from your identity provider or custom provisioning client. Your client sends changes to the SCIM endpoint associated with your Writer organization. Writer applies those changes asynchronously; an API success response confirms the directory request succeeded, while changes in Writer may appear afterward.

SCIM reads return the connection's directory records. They do not report completion of Writer account, team, role, or license changes. Check the resulting state in Writer when validating your integration.

This guide covers Custom SCIM connections using External JWT auth. Complete connection setup before calling the API. SCIM manages provisioning; configure SSO separately for sign-in.

Connect and authenticate

In AI Studio → Admin settings → Access & provisioning → SCIM, follow the setup flow, select Custom SCIM, and select External JWT auth. Use the issuer and token-validation settings agreed during onboarding.

Copy the complete SCIM endpoint URL shown for your connection. Use it as BASE_URL throughout this guide, appending the resource path once. Each environment and connection has its own configuration; use the demo connection for initial testing.

Obtain a JWT access token from your organization's authorization server using your approved OAuth configuration. Send it with every SCIM request:

http

Authorization: Bearer <CUSTOMER_ISSUED_ACCESS_TOKEN>
Accept: application/scim+json
Content-Type: application/scim+json

Content-Type is needed for requests with a JSON body. Token acquisition and renewal follow your authorization server's contract. The token must satisfy the validation settings configured for this connection. Keep the discovery and signing-key endpoints accessible as agreed during setup.

For an initial read-only connectivity check:

sh

curl --fail-with-body "$BASE_URL/Users?startIndex=1&count=1" \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    --header 'Accept: application/scim+json'

Resource endpoints

All paths below are relative to BASE_URL. {id} is the identifier returned by the SCIM API.

Discovery endpoints are GET /ServiceProviderConfig, GET /Schemas, and GET /ResourceTypes. Inspect them for advertised capabilities and schema metadata. Optional SCIM features need separate verification before use.

User model and examples

Send a stable externalId from your source directory, a unique userName, a primary work email, and the user's given and family names. For the basic mapping, use the work email as userName. Writer's provisioning integration consumes the mapped email, given name, and family name.

The email domain must be configured for the target Writer organization before provisioning; a new email must also pass that check on update. An email change cannot take an address already used by another Writer account. Writer may reuse an existing account with the same email when provisioning organization membership. Names and email belong to the shared Writer account, so updates are not isolated to this organization.

Use PATCH with explicit, non-empty profile values. Removing or omitting a profile attribute is not a supported way to clear its Writer value: omitted names can retain existing values, and blank names can receive a fallback. Do not assume a PUT replacement clears the corresponding Writer profile fields. Additional attributes accepted by the directory, including user displayName, do not automatically update Writer's profile.

Persist the returned SCIM id and use it for subsequent resource URLs and group memberships. Treat it as opaque; it is separate from your externalId and from Writer application user IDs. The core attribute definitions are described in RFC 7643.

Create — POST /Users

JSON

{
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
     "externalId": "employee-1042",
     "userName": "[email protected]",
     "name": { "givenName": "Alex", "familyName": "Morgan" },
     "emails": [
          { "value": "[email protected]", "type": "work", "primary": true }
     ],
     "active": true
}

Illustrative response, with server-generated metadata omitted:

JSON

{
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
     "id": "<RETURNED_USER_ID>",
     "externalId": "employee-1042",
     "userName": "[email protected]",
     "name": { "givenName": "Alex", "familyName": "Morgan" },
     "emails": [
          { "value": "[email protected]", "type": "work", "primary": true }
     ],
     "active": true
}

Read — GET /Users/{id} returns a user resource. A collection request uses a SCIM list envelope:

JSON

{
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
     "totalResults": 0,
     "startIndex": 1,
     "itemsPerPage": 0,
     "Resources": []
}

Use startIndex and count for pagination. A user lookup can use a URL-encoded filter such as userName eq "[email protected]". Verify any additional filter expressions your client needs during onboarding.

Update — PATCH /Users/{id}

JSON

{
 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
 "Operations": [
    { "op": "replace", "path": "name.givenName", "value": "Alexandra" }
 ]
}

Deactivate — PATCH /Users/{id}

JSON

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

Delete — DELETE /Users/{id}, with no request body.

Writer's current integration requires automatic removal of inactive directory users for active: false to trigger offboarding. Confirm that configuration with Writer during onboarding. Retaining an inactive directory record is not a supported suspension mode for this integration. A returning user receives a new directory ID; update your mapping and restore the intended group memberships. Do not rely on reactivating the previous ID. Offboarding removes membership in the target Writer organization; it is not a global account deletion or a request to erase all stored Writer content.

Groups and membership

Create — POST /Groups

JSON

{
 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
 "externalId": "group-27",
 "displayName": "Content Operations",
 "members": []
}

Illustrative response, with metadata omitted:

JSON

{
 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
 "id": "<RETURNED_GROUP_ID>",
 "externalId": "group-27",
 "displayName": "Content Operations",
 "members": []
}

Add a member — PATCH /Groups/{id}

JSON

{
 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
 "Operations": [
     { "op": "add", "path": "members", "value": [{ "value": "<RETURNED_USER_ID>" }] }
 ]
}

Remove a member — PATCH /Groups/{id}

JSON

{
 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
 "Operations": [
     { "op": "remove", "path": "members[value eq \"<RETURNED_USER_ID>\"]" }
 ]
}

Provision users before adding them to groups. A SCIM group represents a provisioning group; creating or renaming it does not create or rename a Writer team. Writer applies membership changes using the group's configured team, role, and seat settings. Review those settings before assigning members. Removing a group membership or deleting a group is separate from deprovisioning a user; other group assignments and organization defaults can continue to grant access.

Responses and integration limits

The standard response patterns are 201 for creation, 200 for reads, and 200 with a resource or 204 without a body for updates. Deletion returns 204. Do not require a JSON body on every successful write. HTTP methods, list envelopes, PATCH operations, and error formats are defined in RFC 7644.

Treat 400 as a request/schema problem, 401 as an authentication problem, 404 as a missing resource, and 409 as a conflict requiring reconciliation. For throttling or transient failures, use bounded retries with backoff and respect Retry-After when provided. After an ambiguous create response, look up the resource before retrying creation.