Introduction

Uplifter supports SCIM for enterprise clients.

SCIM (System for Cross-domain Identity Management) allows enterprise users to manage access to applications at scale. It is favored by security teams because access control is automated — users do not need to log in to Uplifter to manage users. As employees join, leave, or change roles in the organization, their access to Uplifter can be automatically adjusted or revoked via their identity provider.

Technical Overview

Base URL:

https://access.uplifter.tech/scim/v2

Interactive Documentation:

A ReDoc site is available for API documentation:

https://access.uplifter.tech/redoc#tag/SCIM_v2

Authentication

Uplifter’s SCIM service is part of our public API. An API key can be generated from the settings page by users with admin-level permissions.

This API key can be used as a bearer token:

Authorization: Bearer <apikey>

Or as a custom header:

x-api-key: <apikey>

The implementation is based on SCIM 2.0, with additional support for Roles and Entitlements.

Supported Endpoints:

Endpoint	Methods Supported
/Users	GET, POST, PATCH, PUT
/Groups	GET, POST, PATCH, PUT
/Roles	GET
/Entitlements	GET
/Schemas	GET
/ServiceProviderConfig	GET

• Filtering is supported on /Users.
• Unsupported Endpoints: /Bulk /Me /Search
• Groups can only be filtered on their displayName

Permissions Hierarchy in Uplifter

Uplifter provides three main ways to manage user access through SCIM: Roles, Entitlements, and Groups. These mechanisms can be used individually or in combination, but they serve different purposes and operate at different levels. 

Where a user has not had an explicit role, entitlement or group set, they are by default assigned the regular role, with regular access to each workspace.

Whenever a user is added via SCIM or whenever their permissions change, they are sent an email indicating this from support@uplifter.ai 

1. Roles — Global Access Level

Roles define a user's access level across all workspaces in Uplifter. There are two roles:

• admin: Full access, including workspace settings and management.
• regular: Limited access — users can create/edit campaign links but cannot manage settings.

Roles are applied at a global level. If a user is given the "admin" role, they are considered an admin in every workspace.

2. Entitlements — Workspace-Specific Permissions (Recommended)

Entitlements allow fine-grained control over permissions at the workspace level. For every workspace, two entitlements are created:

<Workspace Name>: Admin

<Workspace Name>: Regular

Entitlements are the most precise way to manage access and are preferred when you need to assign users to specific workspaces with specific permissions.

Example: If you have two workspaces, “Paid Media” and “SEO”, you could assign a user the following entitlements:

• “Paid Media: Admin”
• “SEO: Regular” to another

This ensures each user has access only to the correct workspace, with the correct permission level.

3. Groups — Indirect Access Control

Groups are used to sync user groups from your identity provider (e.g., Okta or Entra ID) into Uplifter. These groups do not carry permissions on their own, but once synced, you can assign workspace permissions to a group via the Uplifter settings page.

Users in a synced group inherit the permissions assigned to that group in Uplifter.

However, due to SCIM limitations, permissions cannot be directly applied to a group through SCIM — they must be set manually in Uplifter after syncing.

Summary:

Mechanism	Scope	Where Set	How Permissions Are Assigned	Recommended Use
Roles	Global	SCIM (user POST/PUT/PATCH)	Sets a user's permission as regular/admin across all workspaces	Simple workspace setups where speed or ease of management is prioritised.
Entitlements	Per workspace	SCIM (user POST/PUT/PATCH)	Sets a user's permission for one or more workspace-specific admin/regular access	Generally preferred for granular control
Groups	Identity provider	SCIM + in uplifter settings	Groups are synced into Uplifter. Permission levels are set for the group for workspaces from the Uplifter settings page. Group members inherit the permissions set at the group level.	Recommended for organizations with significant numbers of users, where granular control is unfeasible, or when using Microsoft Entra where roles/entitlements are not supported

 

SCIM endpoint specifications

This section shows the available SCIM endpoints, and contains sample requests and responses where appropriate.

ServiceProviderConfig

The Service Provider Configuration endpoint allows SCIM clients (like identity providers) to discover what features are supported by Uplifter’s SCIM API.

• GET /ServiceProviderConfig

Retrieves the service provider’s SCIM feature configuration.

Schemas

Schemas define the structure of SCIM objects such as Users, Groups, Roles, and Entitlements. This endpoint helps identity providers understand what fields and formats to use.

Uplifter supports the following SCIM schemas:

• • ServiceProviderConfig

  • Schema

  • User

  • Group

  • Roles
  • Entitlements

These custom schemas are used for managing user permissions across and within Uplifter workspaces.

• GET /Schemas

Retrieves the list of supported schemas.

• GET /Schemas/{schema_type}

Retrieves a specific schema.

Entitlements

Entitlements are optional and represent fine-grained permissions. These are used to assign user access to specific workspaces in Uplifter.

• GET /Entitlements

Returns all available entitlements — one per workspace and permission level. For each workspace in Uplifter, two entitlements are generated: one for Admin, one for Regular.

• GET /Entitlements/{entitlement_id}

Returns details for a specific entitlement.

Example: If a workspace is named “Paid Media,” the following entitlements will be available:

• Paid Media: Admin

• Paid Media: Regular

We recommend using entitlements where possible for managing workspace-level access.

Entitlements can be assigned during user creation (POST) or updated using PATCH/PUT.

Roles

Roles are optional and designate a user’s permission level across all Uplifter workspaces.

Available roles:

• Admin

Admin users can create and edit campaign links as well as access workspace settings in the settings page of uplifter.

• Regular

Regular users can create and edit links, but can't access workspace settings.

• GET /Roles

Returns the list of roles.

GET /Roles/{role_id} Returns a specific role.

Roles can be assigned during user creation (POST) or updated using PATCH/PUT.

Users

Users represent individual people in the organization. The SCIM /Users endpoint manages user provisioning, updates, and deactivation.

externalId should be set to the user’s ID from the identity provider:

• For Microsoft Entra ID: use the objectId

• For Okta: use the "sub" claim

userName must match the user’s primary email.

The password field is included only for schema compliance, it is not supported beyond this.

• GET /Users

Lists all users provisioned via SCIM. Filtering is supported.

• GET /Users/{user_id}

Returns a specific user.

• POST /Users

Creates a new user managed by SCIM.

Note: If the user limit has been reached, the API will respond with the following error:

{
  "status": 403,
  "detail": "You have used all your user licences, contact support@uplifter.ai to increase your licences.",
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ]
}

 

Create a user (no entitlement, group or role specified - will be assigned the "regular" role by default)

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "scimtest@uplifter.onmicrosoft.com",
    "name": {
        "givenName": "Scim",
        "familyName": "Test"
    },
    "emails": [{
        "primary": true,
        "value": "scimtest@uplifter.onmicrosoft.com",
        "type": "work"
    }],
    "displayName": "Scim Test",
    "externalId": "e3277e4b-f243-4ed1-ac7d-5a83d792bdd1",
    "active": true
}

Create a user (with entitlement - they will have only access to the workspace in the entitlement:

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "scimtest@uplifter.onmicrosoft.com",
    "name": {
        "givenName": "Scim",
        "familyName": "Test"
    },
    "emails": [{
        "primary": true,
        "value": "scimtest@uplifter.onmicrosoft.com",
        "type": "work"
    }],
    "entitlements": [
      {
        "value": "04d0193b-a7d8-4edb-9933-f6a681c475bd;admin",
        "display": "test - ga4 - account 2: Admin",
        "$ref": null,
        "type": "Permission",
        "primary": false
      }
    ],
    "displayName": "Scim Test",
    "externalId": "e3277e4b-f243-4ed1-ac7d-5a83d792bdd1",
    "active": true
}

Create a user (with role - user will have regular access to all workspaces)

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "scimtest@uplifter.onmicrosoft.com",
    "name": {
        "givenName": "Scim",
        "familyName": "Test"
    },
    "emails": [{
        "primary": true,
        "value": "scimtest@uplifter.onmicrosoft.com",
        "type": "work"
    }],
    "roles": [
      {
      "schemas": [
        "urn:uplifter:schemas:extension:1.0:Role"
      ],
      "value": "regular",
      "display": "Regular",
      "enabled": true,
      "$ref": "http://localhost:8000/scim/v2/Roles/regular",
      "type": "Permission"
    }
    ],
    "displayName": "Scim Test",
    "externalId": "e3277e4b-f243-4ed1-ac7d-5a83d792bdd1",
    "active": true
}

Create a user (with role and entitlement - user will have regular access to all workspaces, and admin access to the workspace specified by the entitlement)

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "scimtest@uplifter.onmicrosoft.com",
    "name": {
        "givenName": "Scim",
        "familyName": "Test"
    },
    "emails": [{
        "primary": true,
        "value": "scimtest@uplifter.onmicrosoft.com",
        "type": "work"
    }],
    "entitlements": [
       {
        "value": "04d0193b-a7d8-4edb-9933-f6a681c475bd;admin",
        "display": "test - ga4 - account 2: Admin",
        "$ref": null,
        "type": "Permission",
        "primary": false
      }
    ],
    "roles": [
      {
      "schemas": [
        "urn:uplifter:schemas:extension:1.0:Role"
      ],
      "value": "regular",
      "display": "Regular",
      "enabled": true,
      "$ref": "http://localhost:8000/scim/v2/Roles/admin",
      "type": "Permission"
    }
    ],
    "displayName": "Scim Test",
    "externalId": "e3277e4b-f243-4ed1-ac7d-5a83d792bdd1",
    "active": true
}

• PUT /Users/{user_id}

Replaces a user’s information (use PATCH instead when possible).

User (removes all set entitlements and roles):

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "scimtest@uplifter.onmicrosoft.com",
    "name": {
        "givenName": "Scimmy",
        "familyName": "Testy"
    },
    "emails": [{
        "primary": true,
        "value": "scimtest@uplifter.onmicrosoft.com",
        "type": "work"
    }],
    "displayName": "Scimmy Testy",
    "externalId": "e3277e4b-f243-4ed1-ac7d-5a83d792bdd1",
    "active": true
}

User (remove entitlements)

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "scimtest@uplifter.onmicrosoft.com",
    "name": {
        "givenName": "Scim",
        "familyName": "Test"
    },
    "emails": [{
        "primary": true,
        "value": "scimtest@uplifter.onmicrosoft.com",
        "type": "work"
    }],
    "roles": [
      {
      "schemas": [
        "urn:uplifter:schemas:extension:1.0:Role"
      ],
      "value": "regular",
      "display": "Regular",
      "enabled": true,
      "$ref": "http://localhost:8000/scim/v2/Roles/admin",
      "type": "Permission"
    }
    ],
    "displayName": "Scim Test",
    "externalId": "e3277e4b-f243-4ed1-ac7d-5a83d792bdd1",
    "password": "1234",
    "active": true
}

User (update entitlements)

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "scimtest@uplifter.onmicrosoft.com",
    "name": {
        "givenName": "Scim",
        "familyName": "Test"
    },
    "emails": [{
        "primary": true,
        "value": "scimtest@uplifter.onmicrosoft.com",
        "type": "work"
    }],
    "entitlements": [
       {
        "value": "04d0193b-a7d8-4edb-9933-f6a681c475bd;regular",
        "display": "test - ga4 - account 2: Regular",
        "$ref": null,
        "type": "Permission",
        "primary": false
      }
    ],
    "displayName": "Scim Test",
    "externalId": "e3277e4b-f243-4ed1-ac7d-5a83d792bdd1",
    "password": "1234",
    "active": true
}

• PATCH /Users/{user_id}

Updates selected user attributes.

Update values

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

Add an entitlement to a user 

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "value": {
        "entitlements": [
          {
            "value": "39585a7c-8ec0-4bf9-a7cb-2cff592f4bb5;admin"
          }
        ]
      }
    }
  ]
}

Replace entitlements - removes existing entitlements and adds the selected ones.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "value": {
        "entitlements": [
          {
            "value": "39585a7c-8ec0-4bf9-a7cb-2cff592f4bb5;regular"
          },
          {
            "value": "04d0193b-a7d8-4edb-9933-f6a681c475bd;admin"
          }
        ]
      }
    }
  ]
}

Remove Role:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "remove",
      "value": {
        "roles": [
          {
            "value": "regular"
          }
        ]
      }
    }
  ]
}

• DELETE /Users/{user_id}

Deactivates the user and removes them from the license count. Their links remain, and their audit history is retained. To restore access, POST the user again.

Returns none.

 

Groups

Groups represent groups created in the identity provider. These groups can be synced with Uplifter.

While SCIM doesn’t natively allow setting group permissions directly from the identity provider, Uplifter allows you to assign workspace access to synced groups via the settings page within Uplifter. Users added to a group inherit the group’s permissions.

• GET /Groups

Returns a list of synced groups.

• GET /Groups/{group_id}

Returns details for a specific group.

• POST /Groups

Creates a new group (and add members to the group)

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "Example Group",
  "members": [
    {
      "value": "65ef76c9-df94-47a6-b314-4cff76aae126"
    }
  ]
}

• PUT /Groups/{group_id}

Replace all attributes of a group in Uplifter.

Set to an empty array to remove all members of the group:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "Example Groupo",
  "members": []
}

Include the user to add them

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "Example Group",
  "members": [
    {
      "value": "65ef76c9-df94-47a6-b314-4cff76aae126"
    }
  ]
}

• PATCH /Groups/{group_id}

Updates attributes like display name or membership.

Add a member to a group:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "members[value eq '65ef76c9-df94-47a6-b314-4cff76aae126']"  
      
    }
  ]
}

The alternative format is also supported:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "65ef76c9-df94-47a6-b314-4cff76aae126"
        }
      ]
    }
  ]
}

Remove a user from a group:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq '65ef76c9-df94-47a6-b314-4cff76aae126']"  
      
    }
  ]
}

Again, the alternative format is also supported:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "remove",
      "path": "members",
      "value": [
        {
          "value": "65ef76c9-df94-47a6-b314-4cff76aae126"
        }
      ]
    }
  ]
}

Remove all members:

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

Replace the member list with an updated list: 

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "members",
      "value": [
        {
          "value": "65ef76c9-df94-47a6-b314-4cff76aae126"
        }
      ]
    }
  ]
}

 

• DELETE /Groups/{group_id}

Deletes a group. Users in the group are not deleted.

Note: Entitlements are recommended over groups and roles for managing permissions.