SCIM: Technical reference

• Prerequisites
• Enable SCIM in DeepL account
• Service endpoints and authentication
• Resources and endpoints
• Standard operations
• Attributes consumed by DeepL
• Common SCIM actions interpreted by DeepL

These instructions explain how IT admins can set up SCIM user provisioning for their team after setting up single sign-on (SSO) with any identity provider that supports the SCIM 2.0 protocol. For more information about SCIM user provisioning, see this article. 

This article describes DeepL's SCIM endpoints and supported operations. It also explains how DeepL handles attributes and interprets SCIM requests without identity provider-specific instructions.

DeepL follows the SCIM messages from the identity provider. The provisioning cycles depend on the identity providers' behavior, not DeepL.

Prerequisites

• Admin access to DeepL
• Single sign on (SSO) is setup for DeepL. If you haven't set up SSO, follow the instructions.
  • OpenID Connect
  • SAML
• Remove JIT group synchronization and groups, if it was enabled in a previous setup. Follow the instructions in this article.
  • Existing users who are not assigned the DeepL app in the identity provider are not automatically deleted by SCIM. Delete them manually if they are no longer needed.
  • Existing groups that are not granted access in the identity provider are not automatically deleted. Delete them manually if they are no longer needed.
  • Groups created previously (e.g., via JIT group synchronization) can be managed by SCIM going forward. 
• If you're using the OpenID Connect protocol in your SSO setup, check if the application was created via the Enterprise application and not via the App registration. Follow the instructions in this article.

Enable SCIM in DeepL account

1. Go to the Settings of your DeepL account
2. In section Team and User provisioning configuration, click Manage user provisioning

3. Select Enable SCIM provisioning
   An SCIM admin API key is created. You need this API key for your configuration. For more information, see this article.  

   If you've previously set up JIT group synchronization, make sure to disable it to avoid any user provisioning issues. Before disabling JIT group synchronization, export your existing groups and users. 

Service endpoints and authentication

• Base URL (Tenant URL): https://scim.deepl.com
• Authentication (Secret Token): Use the admin API key which is automatically created when enabling SCIM for your team. For more information, on how to access your admin API keys, see this article. Your identity provider’s SCIM connector must send this token when calling the SCIM endpoints.

Your identity provider may label this as Bearer token, Secret token, or similar. Supply the SCIM admin API key in the field your connector provides for SCIM authentication.

Resources and endpoints

Users:

POST /Users

PATCH /Users/{id}

DELETE /Users/{id}

Groups:

POST /Groups

PATCH /Groups/{id}

DELETE /Groups/{id}

These paths and verbs represent the information that DeepL receives from identity providers during standard operations.

Standard operations

Users: 

• Provision (create)
• Update (attributes and status)
• Deprovision

Groups: 

• Provision (create)
• Update (name and group membership)
• Deprovision

Attributes consumed by DeepL

Users: 

userName

active

externalId

name.formatted

locale

Groups: 

externalId

displayName

Common SCIM actions interpreted by DeepL

In the DeepL admin account, users who are listed as License unassigned means that the identity provider has removed their license (e.g., by unassigning the app or setting active=false). 

Example payloads (generic SCIM) 

These are only examples for reference. Your identity provider will generate equivalent requests.

Grant access

POST /Users
Content-Type: application/scim+json

{
  "userName": "jane.doe@example.com",
  "externalId": "idp-12345",
  "name": { "formatted": "Jane Doe" },
  "preferredLanguage": "en",
  "active": true
}

Deactivate user

PATCH /Users/2819c223-7f76-453a-919d-413861904646
Content-Type: application/scim+json

{
 "Operations": [
   { "op": "Replace", "path": "active", "value": false }
 ]
}

Add user to a group

PATCH /Groups/47aa02c1-5f27-4f3f-9d8d-1e3f2c5b9d10
Content-Type: application/scim+json

{
 "Operations": [
   {
     "op": "Add",
     "path": "members",
     "value": [{ "value": "2819c223-7f76-453a-919d-413861904646" }]
   }
 ]

Create a group

POST /Groups
Content-Type: application/scim+json

{
 "displayName": "DeepL-Translator",
 "externalId": "grp-98765",
 "members": []
}

Testing provisioning

If any operation fails during testing or provisioning contact us and share the full error payload, including the X-trace-id request identifier if your identity provider exposes. This information helps us to investigate server-side logs. 
You can also verify the results in your DeepL admin account (e.g., new users or groups appearing under Users tab).