SCIM 2.0 Provisioning

Cognethics supports SCIM 2.0 user provisioning and group-membership updates. Your identity provider creates, reads, updates, and deletes users in Cognethics over the SCIM v2 API, authenticated with a per-tenant bearer token.

Quick Reference

Endpoints

Service Provider Configuration, Resource Types, Schemas

GET /scim/v2/ServiceProviderConfig
GET /scim/v2/ResourceTypes
GET /scim/v2/Schemas

These three are unauthenticated capability-discovery endpoints — point your IdP's SCIM setup wizard at ServiceProviderConfig first.

User Management

List users

GET /scim/v2/Users?filter=userName eq "person@acme.example"&sortBy=userName&sortOrder=ascending&startIndex=1&count=100

Get a single user

GET /scim/v2/Users/{id}

Create a user

POST /scim/v2/Users
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "person@acme.example",
  "name": {
    "givenName": "Jane",
    "familyName": "Smith"
  },
  "emails": [
    { "value": "person@acme.example", "type": "work", "primary": true }
  ],
  "active": true
}

A provisioned user stays inactive until active is set true on the request, or your tenant has auto-activation enabled.

Update a user

PUT /scim/v2/Users/{id}
PATCH /scim/v2/Users/{id}

Delete a user

DELETE /scim/v2/Users/{id}

Group Management

POST /scim/v2/Groups
PUT /scim/v2/Groups/{id}
PATCH /scim/v2/Groups/{id}

Push group membership by creating the group, then updating its members array with PUT or PATCH:

PUT /scim/v2/Groups/{id}
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering Team",
  "members": [
    { "value": "{user-id}", "display": "person@acme.example" }
  ]
}

Attribute Mapping

Bearer Token Authentication

SCIM v2 endpoints are protected by a per-tenant bearer token, generated in Admin → Enterprise SSO → SCIM:

curl -H "Authorization: Bearer scim_…" \
  https://your-tenant.cognethics.com/scim/v2/Users

The token is shown in plaintext exactly once at mint time and stored hashed — save it immediately. Rotate it from the same console page if it's lost or compromised; the previous token is invalidated on rotation. Enable SCIM only after a token exists. An optional per-tenant IP allow-list can further restrict which addresses may call the endpoint — a call from outside it is refused with 403.

Never commit tokens to version control or share them publicly.

Filtering, Sorting, Pagination

Filters take exactly one clause: attribute operator "value", value in double quotes.

Filterable attributes: userName, name.givenName, name.familyName, emails.value, active, title, id, externalId.

Sorting takes the same attribute set:

?sortBy=userName&sortOrder=ascending

Pagination:

?startIndex=1&count=100

count defaults to 100 and can be raised to a maximum of 1,000.

Error Responses

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": 400,
  "scimType": "invalidValue",
  "detail": "Duplicate user: person@acme.example already exists"
}

scimType values: invalidFilter, invalidValue, uniqueness, notFound.

Configuration

A tenant administrator configures SCIM from the Cognethics console at Admin → Enterprise SSO → SCIM:

1. Mint a bearer token. Cognethics shows the plaintext token exactly once — copy it immediately into a secrets manager. The token is hashed at rest and cannot be retrieved later; if lost, rotate to mint a new one.
2. Enable SCIM. This unlocks the SCIM v2 endpoint at https://your-tenant.cognethics.com/scim/v2/ for your IdP to call.
3. Configure your IdP with the SCIM base URL and the bearer token (see the recipes below).

Common IdP Configurations

Okta

1. In Okta Admin: Applications → Create App Integration → SAML + SCIM.
2. On the Provisioning tab, set the SCIM base URL to https://your-tenant.cognethics.com/scim/v2/ and the OAuth Token to the bearer token minted in the Cognethics console.
3. Okta begins provisioning users; enable group push to sync POST /Groups and PUT /Groups/{id} member updates.

Azure AD / Microsoft Entra ID

1. In Entra: Enterprise applications → Provisioning, set Provisioning Mode to Automatic.
2. Set the Tenant URL to https://your-tenant.cognethics.com/scim/v2/ and the Secret Token to the bearer token minted in the Cognethics console.
3. Entra begins provisioning users and pushing group membership.

Rate Limits

SCIM requests are limited to 1,000 per hour and 100 per minute, per tenant and per calling address.

Troubleshooting

"Unauthorized" or "Invalid token":

• Verify the bearer token in your IdP matches the value minted in the Cognethics console.
• If the token may have been rotated, mint a new one in Admin → Enterprise SSO → SCIM and update your IdP.

"Duplicate user" error:

• Check whether the user already exists in Cognethics under a different email or userName.

Changes not syncing to Cognethics:

• Check that the SCIM endpoint is reachable from your IdP.
• Verify the bearer token is correct and has not been rotated out from under your IdP configuration.

Support

For SCIM provisioning help, reach our support team through the contact form.

Back to Enterprise Authentication · See also SAML 2.0 Single Sign-On