SCIM Provisioning

UniAuth supports SCIM 2.0 (System for Cross-domain Identity Management) for automated user provisioning and deprovisioning. Connect your existing identity provider — such as Okta, Azure AD, or OneLogin — to automatically sync users into UniAuth when they join or leave your organization.

Setup

Any owner or admin of an Enterprise organization can issue a SCIM token themselves — no support ticket required. The token is bound to one of the org's OAuth clients, and SCIM authentication resolves back to that client.

Open your organizations and head to a team's /org/<id>/admin/clients page, where each OAuth client has a Generate SCIM token action (the same screen revokes it). Under the hood it calls:

POST /api/org/<orgId>/clients/<clientId>/scim-token
Authorization: Bearer <org-admin-session>

# Response (shown ONCE — cannot be retrieved again)
{
  "success": true,
  "data": {
    "token": "uni_scim_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

# To revoke:
DELETE /api/org/<orgId>/clients/<clientId>/scim-token

If the organization is not on the Enterprise plan, this endpoint returns 402 with upgrade_required — upgrade the team to Enterprise to enable provisioning. Re-issuing always replaces the previous token, and a DELETE revokes it immediately.

Base URL

All SCIM endpoints are served under:

https://uniauth.id/api/scim/v2

When configuring your IdP, use this as the SCIM connector base URL.

Authentication

All SCIM requests must include a bearer token in the Authorization header:

Authorization: Bearer scim_abc123def456...

Tokens are scoped to a specific OAuth client and can be revoked or rotated from the admin panel.

Endpoints

User Schema Mapping

SCIM attributes are mapped to UniAuth user fields as follows:

Example: Create User

POST /api/scim/v2/Users
Content-Type: application/json
Authorization: Bearer scim_abc123def456...

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jane@example.com",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "displayName": "Jane Doe",
  "active": true,
  "title": "Software Engineer",
  "locale": "en-US",
  "timezone": "America/New_York"
}

Example: Response

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userName": "jane@example.com",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "displayName": "Jane Doe",
  "active": true,
  "title": "Software Engineer",
  "locale": "en-US",
  "timezone": "America/New_York",
  "meta": {
    "resourceType": "User",
    "created": "2026-02-26T14:30:00.000Z",
    "lastModified": "2026-02-26T14:30:00.000Z",
    "location": "https://uniauth.id/api/scim/v2/Users/550e8400-e29b-41d4-a716-446655440000"
  }
}

Filtering

The GET /api/scim/v2/Users endpoint supports SCIM filtering via the filter query parameter. Supported operators:

• eq — Equal
• co — Contains
• sw — Starts with

Filter Examples

# Find user by exact email
GET /api/scim/v2/Users?filter=userName eq "jane@example.com"

# Search by display name (contains)
GET /api/scim/v2/Users?filter=displayName co "Jane"

# Find users whose name starts with "J"
GET /api/scim/v2/Users?filter=name.givenName sw "J"

Pagination

List endpoints support pagination with startIndex and count parameters. The maximum page size is 100.

GET /api/scim/v2/Users?startIndex=1&count=25

The response includes pagination metadata:

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

Provisioning from Okta

To set up SCIM provisioning from Okta:

• In Okta, go to Applications → Create App Integration
• Select SCIM 2.0 as the provisioning method
• Set the SCIM connector base URL to https://uniauth.id/api/scim/v2
• Set the authentication mode to HTTP Header
• Paste your UniAuth SCIM bearer token
• Enable the desired provisioning features: Create Users, Update User Attributes, Deactivate Users
• Assign users or groups to the application to begin provisioning

Provisioning from Azure AD

To set up SCIM provisioning from Microsoft Entra ID (Azure AD):

• In the Azure portal, go to Enterprise Applications → New Application
• Create a non-gallery application
• Under Provisioning, set the mode to Automatic
• Set the Tenant URL to https://uniauth.id/api/scim/v2
• Set the Secret Token to your UniAuth SCIM bearer token
• Click Test Connection to verify connectivity
• Configure attribute mappings (the defaults generally work with UniAuth's schema)
• Assign users or groups and start provisioning

Error Responses

SCIM error responses follow the standard SCIM error schema. Every error includes a schemas array, a numeric status, an optional scimType, and a human-readable detail message.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "400",
  "scimType": "invalidValue",
  "detail": "Missing required attribute: userName"
}

Groups

UniAuth supports full SCIM Group provisioning. You can create, read, update, and delete groups, as well as manage group membership through standard SCIM operations.

Groups support filtering on displayName with the same operators as Users (eq, co, sw), and the same pagination parameters (startIndex and count). Group membership is managed through the members attribute, where each member references a User by their id.

Deactivation vs Deletion

There are two ways to remove a user's access through SCIM, with different outcomes:

# Deactivate a user (soft removal)
PATCH /api/scim/v2/Users/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
Authorization: Bearer scim_abc123def456...

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

Pagination Details

The list users endpoint supports pagination to handle large user directories efficiently.

• Default page size: 25 users per page
• Maximum page size: 100 users per page (requests exceeding this are capped)
• startIndex: 1-based (the first user is at index 1, not 0)
• totalResults: Reflects the total number of users matching the current filter, not just the current page

# Page through all users, 50 at a time
GET /api/scim/v2/Users?startIndex=1&count=50    # Page 1 (users 1-50)
GET /api/scim/v2/Users?startIndex=51&count=50   # Page 2 (users 51-100)
GET /api/scim/v2/Users?startIndex=101&count=50  # Page 3 (users 101-150)

Continue paginating until startIndex + itemsPerPage exceeds totalResults, or until the Resources array is empty.