SCIM API Integration Guide

Overview

Kordiam supports SCIM 2.0 (System for Cross-domain Identity Management), enabling external identity providers (like Microsoft Entra ID) to automate user management via a secure, standardized REST API.

This Phase 1 implementation includes:

Creating, reading, updating, and deleting users
SCIM-compliant filtering, sorting, and pagination
Schema discovery endpoints

Group management is not yet supported and will return empty lists.

Base URL

All SCIM endpoints are available at:

https://kordiam.app/api/scim/v2

Example:

GET https://kordiam.app/api/scim/v2/Users

Authentication

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

Authorization: Bearer <access_token>

Important: The SCIM API access token must be created by Kordiam. Please reach out to support@kordiam.io to request token generation.

SCIM User Endpoints

Method	Endpoint	Description
GET	`/Users`	List users (supports filters, sorting, pagination)
GET	`/Users/{id}`	Retrieve a specific user
POST	`/Users`	Create a new user
PATCH	`/Users/{id}`	Partially update a user
DELETE	`/Users/{id}`	Delete a user
PUT	`/Users/{id}`	Not supported in Phase 1

Query Features

The SCIM API supports SCIM 2.0 query parameters:

filter – e.g., userName eq "alice@example.com"
sortBy, sortOrder
startIndex, count
attributes, excludedAttributes

Example

GET /api/scim/v2/Users?filter=active eq true&sortBy=name.familyName&count=5
Authorization: Bearer <token>

Supported Attributes

Attribute	Required	Notes
`userName`	Yes*	Must be a valid email or resolved from `emails[]`
`emails[]`	Yes*	At least one valid email is required
`name.givenName` / `name.familyName`	Yes*	Can be derived from `displayName`
`displayName`	Optional	Used to extract given/family name
`phoneNumbers[]`	Optional	Supports types like `mobile` and `work`
`active`	Optional	Defaults to `true`
`userType`	Optional	E.g., "Internal"
`meta.created`	Auto	Set automatically on creation

* Required fields may use fallback logic (e.g., derive names from displayName).

Sample Requests

Create User

POST /api/scim/v2/Users
Authorization: Bearer <token>
Content-Type: application/json

{
  "userName": "alice@example.com",
  "name": {
    "givenName": "Alice",
    "familyName": "Smith"
  },
  "emails": [
    {
      "value": "alice@example.com",
      "primary": true
    }
  ]
}

Update User Name

PATCH /api/scim/v2/Users/123
Authorization: Bearer <token>
Content-Type: application/json

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

Deactivate User

PATCH /api/scim/v2/Users/123
Authorization: Bearer <token>
Content-Type: application/json

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

Delete User

DELETE /api/scim/v2/Users/123
Authorization: Bearer <token>

Note: Users will be scheduled for deletion. Deletion will happen within 2 hours.

Discovery Endpoints

Method	Endpoint	Description
GET	`/ServiceProviderConfig`	Returns SCIM service capabilities
GET	`/Schemas`	Lists available schemas
GET	`/Schemas/{id}`	Returns details of a schema
GET	`/ResourceTypes`	Lists supported resource types
GET	`/ResourceTypes/{id}`	Returns a specific resource type

Group Support (Placeholder Only)

While group support is not implemented in Phase 1, the following endpoint exists for schema compliance:

GET /Groups → returns empty list

Summary

The SCIM API allows identity providers to automate secure, standards-based user management in Kordiam. It’s ideal for provisioning users, keeping data synchronized, and managing access lifecycles with ease. Additional features like group support are planned for future phases.

Reach out to support@kordiam.io if you have any questions.