SCIM (System for Cross-domain Identity Management)

Revised July 14, 2025 16:11

Introduction

Coginiti provides SCIM v2.0 API endpoints for user and group management, enabling integration with identity providers like Azure AD, Okta, and other SCIM-compliant systems.

Base URL

All API URLs referenced in this documentation have the following base URL unless otherwise specified:

{hostname}/api/v1/scim/v2

Authentication

The following API requires authentication with a personal access token created in the Coginiti UI. Please follow the instructions here on how to create a personal access token.

List Users

The given endpoint allows to see the list of users

Endpoint: /Users

Parameters:

count: Maximum number of users to return in the response (e.g., 50).
startIndex: 1-based index specifying where to start the results (e.g., 11).
filter: SCIM-compliant expression to narrow users by attribute (e.g., userName eq "john"). Currently limited to userName equality filters only.

Type of request: GET

Result format: JSON

Request example using curl application:

curl -X GET 'https://{hostname}/api/v1/scim/v2/Users'
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_'

Response

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 1,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
            ],
            "id": "user-id",
            "userName": "john.doe@example.com",
            "active": true,
            "emails": [
                {
                    "value": "john.doe@example.com",
                    "primary": true
                }
            ],
            "name": {
                "givenName": "John",
                "familyName": "Doe",
                "fullName": "John Doe",
                "formatted": "John Doe"
            },
            "displayName": "John Doe",
            "roles": [
                {
                    "value": "admin"
                }
            ],
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "organization": "Example Corp",
                "superUser": false,
                "userStatus": "CONFIRMED",
                "external": false
            },
            "groups": [
                {
                    "value": "group-id",
                    "$ref": "link-to-group",
                    "display": "Group Name"
                }
            ]
        }
    ]
}

Return an object with the following structure:

name	description
schemas	SCIM schema identifiers for the response
totalResults	Total number of users matching the query
startIndex	1-based index of the first result returned
itemsPerPage	Number of users returned in this response
Resources	Array of user objects

"Resources" contains the following object:

name	description
schemas	SCIM schema identifiers for the user response
id	Unique identifier for the user
userName	Username
active	Boolean indicating if the user account is enabled
emails	Array of email addresses containing user primary email
name	Object containing user's name components
displayName	Display name for the user
roles	Array of roles containing selected user role
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User	Enterprise extension containing organization-specific attributes
groups	Array of groups the user belongs to

Filter Limitations

The current SCIM implementation has the following filter limitations:

Only supports userName equality filters: Filters like userName eq "john.doe@example.com" are supported
Other attributes are not supported: Filters on other attributes like active, emails, etc. are not yet implemented
Complex expressions are not supported: Operations like and, or, not, co (contains), sw (starts with), ew (ends with), pr (present), gt (greater than), ge (greater than or equal), lt (less than), le (less than or equal) are not yet implemented
Unsupported filters return all results: If a filter cannot be processed, all users/groups are returned (no filtering applied)

Example supported filter:

userName eq "john.doe@example.com"

Examples of unsupported filters:

active eq true
emails.value eq "john@example.com"
userName co "john"
userName sw "john"
active eq true and userName eq "john"

Errors

condition	status	detail
Invalid authentication token	401	Authentication failed or token expired
Invalid pagination parameters	400	startIndex or count parameters are invalid
Server error	500	Internal server error occurred

Create User

The given endpoint allows to create a user

Endpoint: /Users

Parameters:

name	description
schemas	SCIM schema identifiers for the user request
userName	User's username/email
active	Boolean indicating if the user account is enabled
emails	Array of email addresses containing user primary email
name	Object containing user's name components
displayName	Display name for the user
roles	Array of roles containing selected user role
password	User's password
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User	Enterprise extension containing organization-specific attributes

Type of request: POST

Result format: JSON

Request example using curl application:

curl -X POST 'http://localhost:3000/api/v1/scim/v2/Users' \
--header "Content-Type: application/json" \
--header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
-d '{
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
            ],
            "userName": "testuser1",
            "active": true,
            "emails": [
                {
                    "value": "testuser1@example.com",
                    "primary": true
                }
            ],
            "name": {
                "givenName": "Test",
                "familyName": "User",
                "fullName": "Test User",
                "formatted": "Test User"
            },
            "displayName": "Test User",
            "roles": [
                {
                    "value": "software_engineer"
                }
            ],
            "password": "SecurePass123!",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "organization": "Example Corp",
                "superUser": false,
                "userStatus": "CONFIRMED",
                "external": false
            }
      }'

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "id": "user-id",
    "userName": "john.doe@example.com",
    "active": true,
    "emails": [
        {
            "value": "john.doe@example.com",
            "primary": true
        }
    ],
    "name": {
        "givenName": "John",
        "familyName": "Doe",
        "fullName": "John Doe",
        "formatted": "John Doe"
    },
    "displayName": "John Doe",
    "roles": [
        {
            "value": "admin"
        }
    ],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "organization": "Example Corp",
        "superUser": false,
        "userStatus": "CONFIRMED",
        "external": false
    },
    "groups": []
}

Return an object with the following structure:

name	description
schemas	SCIM schema identifiers for the user response
id	Unique identifier for the user
userName	Username
active	Boolean indicating if the user account is enabled
emails	Array of email addresses containing user primary email
name	Object containing user's name components
displayName	Display name for the user
roles	Array of roles containing selected user role
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User	Enterprise extension containing organization-specific attributes
groups	Array of groups the user belongs to

Errors

condition	status	detail
Invalid authentication token	401	Authentication failed or token expired
Invalid user data	400	Required fields missing or invalid format
User already exists	409	User with this username already exists
Server error	500	Internal server error occurred

Retrieve User

The given endpoint allows to retrieve a specific user by ID

Endpoint: /Users/{id}

Parameters:

id: (String, required): User identifier

Type of request: GET

Result format: JSON

Request example using curl application:

curl -X GET 'https://{hostname}/api/v1/scim/v2/Users/{id}' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_'

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "id": "user-id",
    "userName": "john.doe@example.com",
    "active": true,
    "emails": [
        {
            "value": "john.doe@example.com",
            "primary": true
        }
    ],
    "name": {
        "givenName": "John",
        "familyName": "Doe",
        "fullName": "John Doe",
        "formatted": "John Doe"
    },
    "displayName": "John Doe",
    "roles": [
        {
            "value": "admin"
        }
    ],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "organization": "Example Corp",
        "superUser": false,
        "userStatus": "CONFIRMED",
        "external": false
    },
    "groups": [
        {
            "value": "group-id",
            "$ref": "link-to-group",
            "display": "Group Name"
        }
    ]
}

Return an object with the following structure:

name	description
schemas	SCIM schema identifiers for the user response
id	Unique identifier for the user
userName	Username
active	Boolean indicating if the user account is enabled
emails	Array of email addresses containing user primary email
name	Object containing user's name components
displayName	Display name for the user
roles	Array of roles containing selected user role
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User	Enterprise extension containing organization-specific attributes
groups	Array of groups the user belongs to

Errors

condition	status	detail
Invalid authentication token	401	Authentication failed or token expired
User not found	404	User with specified ID does not exist
Server error	500	Internal server error occurred

Update User

The given endpoint allows to update a specific user

Endpoint: /Users/{id}

Parameters:

id: (String, required): User identifier

Type of request: PUT

Result format: JSON

Request example using curl application:

curl -X PUT 'https://{hostname}/api/v1/scim/v2/Users/{id}' \
  --header "Content-Type: application/json" \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  -d '{
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
            ],
            "userName": "testuser2",
            "active": true,
            "emails": [
                {
                    "value": "testuser2@example.com",
                    "primary": true
                }
            ],
            "name": {
                "givenName": "Jane",
                "familyName": "Smith",
                "fullName": "Jane Smith",
                "formatted": "Jane Smith"
            },
            "displayName": "Jane Smith",
            "roles": [
                {
                    "value": "software_engineer"
                }
            ],
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "organization": "Example Corp",
                "superUser": true,
                "userStatus": "CONFIRMED",
                "external": false
            }
        }'

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "id": "user-id",
    "userName": "john.doe@example.com",
    "active": true,
    "emails": [
        {
            "value": "john.doe@example.com",
            "primary": true
        }
    ],
    "name": {
        "givenName": "John",
        "familyName": "Doe",
        "fullName": "John Doe",
        "formatted": "John Doe"
    },
    "displayName": "John Doe",
    "roles": [
        {
            "value": "admin"
        }
    ],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "organization": "Example Corp",
        "superUser": false,
        "userStatus": "CONFIRMED",
        "external": false
    },
    "groups": [
        {
            "value": "group-id",
            "$ref": "link-to-group",
            "display": "Group Name"
        }
    ]
}

Return an object with the following structure:

name	description
schemas	SCIM schema identifiers for the user response
id	Unique identifier for the user
userName	Username
active	Boolean indicating if the user account is enabled
emails	Array of email addresses containing user primary email
name	Object containing user's name components
displayName	Display name for the user
roles	Array of roles containing selected user role
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User	Enterprise extension containing organization-specific attributes
groups	Array of groups the user belongs to

Errors

condition	status	detail
Invalid authentication token	401	Authentication failed or token expired
Invalid user data	400	Required fields missing or invalid format
Server error	500	Internal server error occurred

Delete User

The given endpoint allows to delete a specific user

Endpoint: /Users/{id}

Parameters:

id: (String, required): User identifier

Type of request: DELETE

Result format: JSON

Request example using curl application:

curl -X DELETE 'https://{hostname}/api/v1/scim/v2/Users/{id}' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_'

Response

{
    "status": "200"
}

Return an object with the following structure:

name	description
status	HTTP status code indicating success

Errors

condition	status	detail
Invalid authentication token	401	Authentication failed or token expired
User not found	404	User with specified ID does not exist
Server error	500	Internal server error occurred

List Groups

The given endpoint allows to see the list of groups

Endpoint: /Groups

Parameters:

count: Maximum number of groups to return in the response (e.g., 50).
startIndex: 1-based index specifying where to start the results (e.g., 11).
filter: SCIM-compliant expression to narrow groups by attribute (e.g., displayName eq "Development Team"). Currently limited to userName equality filters only.

Type of request: GET

Result format: JSON

Request example using curl application:

curl -X GET 'https://{hostname}/api/v1/scim/v2/Groups' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_'

Response

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 1,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "id": "group-id",
            "displayName": "Development Team",
            "description": "Software development team",
            "external": false,
            "members": [
                {
                    "value": "user-id",
                    "display": "John Doe",
                    "$ref": "link-to-user",
                    "type": "USER"
                }
            ]
        }
    ]
}

Return an object with the following structure:

name	description
schemas	SCIM schema identifiers for the response
totalResults	Total number of groups matching the query
startIndex	1-based index of the first result returned
itemsPerPage	Number of groups returned in this response
Resources	Array of group objects

"Resources" contains the following object:

name	description
schemas	SCIM schema identifiers for the group response
id	Unique identifier for the group
displayName	Display name for the group
description	Description of the group
external	Boolean indicating if the group is external
members	Array of group members

Errors

condition	status	detail
Invalid authentication token	401	Authentication failed or token expired
Invalid pagination parameters	400	startIndex or count parameters are invalid
Server error	500	Internal server error occurred

Create Group

The given endpoint allows to create a group

Endpoint: /Groups

Parameters:

name	description
schemas	SCIM schema identifiers for the group request
displayName	Display name for the group
description	Description of the group
external	Boolean indicating if the group is external
members	Array of group members

Type of request: POST

Result format: JSON

Request example using curl application:

curl -X POST 'https://{hostname}/api/v1/scim/v2/Groups' \
  --header "Content-Type: application/json" \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  -d '{
          "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
          "displayName": "Development Team",
          "description": "Software development team",
          "external": false,
          "members": [
              {
                  "value": "user-id",
                  "display": "John Doe",
                  "$ref": "link-to-user",
                  "type": "USER"
              }
          ]
      }'

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": "group-id",
    "displayName": "Development Team",
    "description": "Software development team",
    "external": false,
    "members": [
        {
            "value": "user-id",
            "display": "John Doe",
            "$ref": "link-to-user",
            "type": "USER"
        }
    ]
}

Return an object with the following structure:

name	description
schemas	SCIM schema identifiers for the group response
id	Unique identifier for the group
displayName	Display name for the group
description	Description of the group
external	Boolean indicating if the group is external
members	Array of group members

Errors

condition	status	detail
Invalid authentication token	401	Authentication failed or token expired
Invalid group data	400	Required fields missing or invalid format
Server error	500	Internal server error occurred

Retrieve Group

The given endpoint allows to retrieve a specific group by ID

Endpoint: /Groups/{id}

Parameters:

id: (String, required): Group identifier

Type of request: GET

Result format: JSON

Request example using curl application:

curl -X GET 'https://{hostname}/api/v1/scim/v2/Groups/{id}' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_'

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": "group-id",
    "displayName": "Development Team",
    "description": "Software development team",
    "external": false,
    "members": [
        {
            "value": "user-id",
            "display": "John Doe",
            "$ref": "link-to-user",
            "type": "USER"
        }
    ]
}

Return an object with the following structure:

name	description
schemas	SCIM schema identifiers for the group response
id	Unique identifier for the group
displayName	Display name for the group
description	Description of the group
external	Boolean indicating if the group is external
members	Array of group members

Errors

condition	status	detail
Invalid authentication token	401	Authentication failed or token expired
Group not found	404	Group with specified ID does not exist
Server error	500	Internal server error occurred

Update Group

The given endpoint allows to update a specific group

Endpoint: /Groups/{id}

Parameters:

name	description
id	Group identifier (in URL path)
schemas	SCIM schema identifiers for the group request
displayName	Display name for the group
description	Description of the group
external	Boolean indicating if the group is external
members	Array of group members

Type of request: PUT

Result format: JSON

Request example using curl application:

curl -X PUT 'https://{hostname}/api/v1/scim/v2/Groups/{id}' \
  --header "Content-Type: application/json" \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  -d '{
          "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
          "displayName": "Development Team",
          "description": "Software development team",
          "external": false,
          "members": [
              {
                  "value": "user-id",
                  "display": "John Doe",
                  "$ref": "link-to-user",
                  "type": "USER"
              }
          ]
      }'

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": "group-id",
    "displayName": "Development Team",
    "description": "Software development team",
    "external": false,
    "members": [
        {
            "value": "user-id",
            "display": "John Doe",
            "$ref": "link-to-user",
            "type": "USER"
        }
    ]
}

Return an object with the following structure:

name	description
schemas	SCIM schema identifiers for the group response
id	Unique identifier for the group
displayName	Display name for the group
description	Description of the group
external	Boolean indicating if the group is external
members	Array of group members

Errors

condition	status	detail
Invalid authentication token	401	Authentication failed or token expired
Invalid group data	400	Required fields missing or invalid format
Server error	500	Internal server error occurred

Delete Group

The given endpoint allows to delete a specific group

Endpoint: /Groups/{id}

Parameters:

id: (String, required): Group identifier

Type of request: DELETE

Result format: JSON

Request example using curl application:

curl -X DELETE 'https://{hostname}/api/v1/scim/v2/Groups/{id}' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_'

Response

{
    "status": "200"
}

Return an object with the following structure:

name	description
status	HTTP status code indicating success

Errors

condition	status	detail
Invalid authentication token	401	Authentication failed or token expired
Group not found	404	Group with specified ID does not exist
Server error	500	Internal server error occurred

Introduction

Base URL

Authentication

List Users

Filter Limitations

Create User

Retrieve User

Update User

Delete User

List Groups

Create Group

Retrieve Group

Update Group

Delete Group

Articles in this section