> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lighton.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Can Paradigm automatically provision users?
> This article explains how Paradigm implements the SCIM (System for Cross-domain Identity Management) protocol to enable transparent provisioning and management of users between systems.
This article explains how Paradigm implements the SCIM (System for Cross-domain Identity Management) protocol to enable transparent provisioning and management of users between systems.
## What is SCIM?
SCIM (System for Cross-domain Identity Management) is an open standard that simplifies user management in multi-domain scenarios. It provides a standardized schema and API for creating, reading, updating, and deleting identity data between identity providers and service providers.
Please note that modifications on the users are still possible from the Paradigm admin panel even if you have user provisioning with SCIM activated for your company.
## SCIM Implementation Details
### Supported SCIM Version
Paradigm supports SCIM 2.0 ([RFC 7642](https://datatracker.ietf.org/doc/html/rfc7642), [RFC 7643](https://datatracker.ietf.org/doc/html/rfc7643) and [RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644)).
### Tested Identity Providers
Our SCIM implementation has been tested with:
* Microsoft Entra ID
### Base URL
All SCIM endpoints are accessible via:
```
https://[paradigm-domain]/scim/v2/
```
With `[paradigm-domain]` being the domain name under which is hosted Paradigm. For the Saas platform of LightOn, its value would be `https://paradigm.lighton.ai/scim/v2/`.
### Authentication
To secure the SCIM API, we implemented a token-based authentication using our API key authentication backend.
Each request must include an authorization header:
```
Authorization: Bearer {your-paradigm-api-key}
```
You can generate and manage API keys in the Admin Panel under API Settings.
A Paradigm API key can only be used to manage users part of the same company as the API key owner, no matter the role of the user.
### Supported Endpoints
Here are the SCIM endpoints supported by Paradigm together with their HTTP methods:
| Endpoint | HTTP Method | Description |
| ------------- | ----------- | ------------------------------------------ |
| `/Users` | GET | List/search users |
| `/Users` | POST | Create a user |
| `/Users/{id}` | GET | Get a specific user |
| `/Users/{id}` | PUT | Replace a user's attributes |
| `/Users/{id}` | PATCH | Update a user's attributes |
| `/Users/{id}` | DELETE | Delete a user (Anonymization for Paradigm) |
| `/Groups` | GET | List/search groups |
It is currently not possible to manage groups through the `/Groups` endpoint.
### Supported user SCIM attributes
The SCIM implementation of Paradigm supports the following user attributes:
**Core Attributes**
| Attribute | Description | Required |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `userName` | Unique identifier for the user | Yes |
| `name.givenName` | First name | No |
| `name.familyName` | Last name | No |
| `title` | The user's title, such as "Vice President" | No |
| `preferredLanguage` | Indicates the User's preferred written or spoken language | No |
| `active` | Boolean indicating if user is active | No |
| `emails` | Email addresses, Paradigm only supports one email address per user | Yes |
| `password` | The User's cleartext password. This attribute is intended to be used as a means to specify an initial password when creating a new User or to reset an existing User's password. | No |
### Group Schema
The SCIM implementation of Paradigm supports the following group attributes:
| Attribute | Description | Required |
| ------------- | ------------------------- | -------- |
| `displayName` | Name of the group | Yes |
| `members` | List of member references | No |
### Error Handling
The Paradigm SCIM API endpoints return standard HTTP codes [following the SCIM error format](https://datatracker.ietf.org/doc/html/rfc7644#section-3.7.3):
| Status Code | Description |
| ----------- | ----------------------------------- |
| 200 | Successful operation |
| 201 | Resource created successfully |
| 400 | Bad request (validation error) |
| 401 | Unauthorized (authentication error) |
| 403 | Forbidden (authorization error) |
| 404 | Resource not found |
| 409 | Conflict with existing resource |
| 500 | Internal server error |
Here is an example of error response:
```json theme={null}
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"status": "400",
"detail": "Attribute 'userName' is required"
}
```
## Provisioning Workflow
### User Provisioning
1. The Identity Provider (IdP) initiates a SCIM request to create a user on the `/Users` endpoint
2. Paradigm validates the request and user data
3. A new user account is created with default permissions
4. A success response is returned to the IdP
### User Deprovisioning
1. The Identity Provider (IdP) sends a request to deactivate or delete a user
2. Paradigm validates the request
3. **For deactivation**: User's `active` status is set to `false`
4. **For deletion**: User account is anonymized (Any user data is removed but the behavioral data)
5. A success response is returned to the IdP
Any further SCIM request on the anonymized user will return a `404 Not Found` HTTP response.
## API request/response examples
### User Creation
Request data example:
```http theme={null}
POST /scim/v2/Users
Authorization: Bearer {your-paradigm-api-key}
Content-Type: application/json
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "john.doe@example.com",
"externalId": "ccb1c352-d321-4027-9d17-de03d8d28b2f",
"name": {
"givenName": "John",
"familyName": "Doe"
},
"emails": [
{
"value": "john.doe@example.com",
"primary": true
}
],
"password": "fake-password-value",
"title": "Software Engineer",
"preferredLanguage": "fr-Latn-CA"
}
```
Related response:
```json theme={null}
{
'schemas': ['urn:ietf:params:scim:schemas:core:2.0:User'],
'id': '4',
'externalId': 'ccb1c352-d321-4027-9d17-de03d8d28b2f',
'userName': 'john.doe@example.com',
'name': {
'givenName': 'John',
'familyName': 'Doe',
'formatted': 'John Doe'
},
'displayName': 'John Doe',
'emails': [
{
'value': 'john.doe@example.com',
'primary': True
}
],
'active': True,
'title': 'Software Engineer',
'preferredLanguage': 'fr',
'groups': [],
'meta': {
'resourceType': 'User',
'created': '2025-04-18T08:43:17.679804+00:00',
'lastModified': '2025-04-18T08:43:17.679804+00:00',
'location': 'http://testserver/scim/v2/Users/4'
}
}
```
### Update a User
Request data example:
```http theme={null}
PATCH /scim/v2/Users/a1b2c3d4
Authorization: Bearer {your-paradigm-api-key}
Content-Type: application/json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op": "replace",
"path": "name.givenName",
"value": "Jonathan"
},
{
"op": "replace",
"path": "title",
"value": "Senior Software Engineer"
}
]
}
```
## Troubleshooting
### Authentication Failures
* Verify your API key is valid and not expired
* Verify the owner of the API key has permissions to manage users.
* Ensure the Authorization header is formatted correctly
## Good Practices
1. **Implement Incremental Updates**: Use PATCH operations instead of PUT when possible
2. **Handle API Failures Gracefully**: Implement retry logic with exponential backoff
3. **Maintain IdP Synchronization**: Schedule regular full syncs to ensure consistency
4. **Secure Your API keys**: Rotate tokens regularly and store them securely