Skip to main content
Truthlocks supports SCIM 2.0 for automated user provisioning and group management. Connect your identity provider (Okta, Azure AD, OneLogin, etc.) to automatically create, update, and deactivate users in your Truthlocks tenant.
SCIM provisioning is available on the Business plan and above.

​
How it works

1

Generate a SCIM token

In the console, go to Settings > SCIM and generate a bearer token. This token authenticates your IdP’s SCIM requests.
2

Configure your IdP

In your identity provider, set the SCIM base URL to https://api.truthlocks.com/scim/v2 and paste the bearer token.
3

Sync users and groups

Your IdP pushes user creates, updates, and deactivations to Truthlocks automatically. Group membership changes update role assignments.

​
SCIM base URL

https://api.truthlocks.com/scim/v2
All SCIM requests must include the bearer token in the Authorization header: 
curl -X GET https://api.truthlocks.com/scim/v2/Users \
  -H "Authorization: Bearer scim_your_token_here"

​
Supported operations

​
Users

OperationMethodPathDescription
ListGET/scim/v2/UsersList users with optional filter
CreatePOST/scim/v2/UsersProvision a new user
GetGET/scim/v2/Users/{id}Retrieve a user by SCIM ID
ReplacePUT/scim/v2/Users/{id}Full user replacement
PatchPATCH/scim/v2/Users/{id}Partial update (e.g., deactivate)
DeleteDELETE/scim/v2/Users/{id}Suspend the user

​
Groups

OperationMethodPathDescription
ListGET/scim/v2/GroupsList groups
CreatePOST/scim/v2/GroupsCreate a group mapping
GetGET/scim/v2/Groups/{id}Retrieve a group by SCIM ID
ReplacePUT/scim/v2/Groups/{id}Replace group (re-maps role bindings)
PatchPATCH/scim/v2/Groups/{id}Add or remove members
DeleteDELETE/scim/v2/Groups/{id}Delete group mapping

​
Discovery

MethodPathDescription
GET/scim/v2/ServiceProviderConfigSupported capabilities
GET/scim/v2/SchemasResource schemas
GET/scim/v2/ResourceTypesAvailable resource types

​
Creating a user

curl -X POST https://api.truthlocks.com/scim/v2/Users \
  -H "Authorization: Bearer scim_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane@example.com",
    "name": { "givenName": "Jane", "familyName": "Smith" },
    "emails": [{ "value": "jane@example.com", "primary": true }],
    "active": true
  }'

​
Deactivating a user

IdPs like Okta and Azure AD send a PATCH request to deactivate users: 
curl -X PATCH https://api.truthlocks.com/scim/v2/Users/{id} \
  -H "Authorization: Bearer scim_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{ "op": "replace", "path": "active", "value": false }]
  }'
Deactivated users lose access immediately but their data is retained.

​
Managing SCIM tokens

Generate and manage tokens through the management API: 
# Generate a new token
curl -X POST https://api.truthlocks.com/v1/scim/tokens \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Okta SCIM" }'

# List tokens
curl -X GET https://api.truthlocks.com/v1/scim/tokens \
  -H "Authorization: Bearer <admin_token>"

# Revoke a token
curl -X DELETE https://api.truthlocks.com/v1/scim/tokens/<token_id> \
  -H "Authorization: Bearer <admin_token>"

​
Activity log

All SCIM operations are recorded in an activity log. View recent provisioning events: 
curl -X GET https://api.truthlocks.com/v1/scim/activity \
  -H "Authorization: Bearer <admin_token>"
Activity types include USER_CREATED, USER_DEACTIVATED, USER_PATCHED, GROUP_CREATED, GROUP_UPDATED, and GROUP_DELETED.

​
Seat enforcement

User creation respects your plan’s seat limit. If the limit would be exceeded, the SCIM endpoint returns HTTP 402 and the user is not created. Upgrade your plan or remove inactive users to free seats.

​
Filtering

The SCIM filter query parameter lets your identity provider narrow list responses to specific users or groups. Truthlocks supports filtering on specific SCIM attributes using the operators below.

​
Supported filter attributes

AttributeResourceDescription
userNameUsersThe user’s login identifier (usually an email address)
displayNameUsers, GroupsThe user’s or group’s display name
externalIdUsers, GroupsThe unique identifier assigned by your identity provider
activeUsersWhether the user account is active (true / false)

​
Supported operators

OperatorMeaningExample
eqEqualsuserName eq "jane@example.com"
neNot equalsactive ne false
coContainsuserName co "example.com"
swStarts withuserName sw "jane"
ewEnds withuserName ew "@example.com"
Combine operators using and / or for complex queries: 
# Find active users whose username contains "example.com"
curl -G https://api.truthlocks.com/scim/v2/Users \
  -H "Authorization: Bearer scim_your_token_here" \
  --data-urlencode 'filter=active eq true and userName co "example.com"'

# Find users starting with "jane" or "john"
curl -G https://api.truthlocks.com/scim/v2/Users \
  -H "Authorization: Bearer scim_your_token_here" \
  --data-urlencode 'filter=userName sw "jane" or userName sw "john"'

# Look up a user by their IdP-assigned external ID
curl -G https://api.truthlocks.com/scim/v2/Users \
  -H "Authorization: Bearer scim_your_token_here" \
  --data-urlencode 'filter=externalId eq "00u1a2b3c4d5e6f7g8h9"'

# Find a user by display name
curl -G https://api.truthlocks.com/scim/v2/Users \
  -H "Authorization: Bearer scim_your_token_here" \
  --data-urlencode 'filter=displayName eq "Jane Smith"'
Filtered results are capped at 200 items per response. If your IdP syncs more than 200 users or groups, it should paginate using the startIndex and count parameters alongside the filter.

​
Common IdP filter patterns

Most identity providers send filters automatically during sync. Here are the patterns that Truthlocks handles:
IdPTypical filter sent
OktauserName eq "user@example.com"
Azure ADuserName eq "user@example.com", displayName co "Smith", or externalId eq "id"
OneLoginuserName sw "user" or externalId eq "id"
If your IdP sends a filter using any of the supported attributes and operators listed above, Truthlocks processes it correctly. You do not need to configure anything on the Truthlocks side.

​
Supported capabilities

CapabilitySupported
PatchYes
BulkNo
FilterYes — eq, ne, co, sw, ew on userName, displayName, externalId, active with and / or (max 200 results)
SortNo
Change passwordNo
ETagNo