SCIM provisioning

Let your identity provider manage your Truto team: when you assign someone to the Truto app in your IdP, they join the team, and when you unassign or deactivate them, they leave it. Groups your IdP pushes can grant roles and environment access.

truto scim-groups list --team-id <team_id>

Before you start

You need an active SSO connection that tells Truto what access new people get. SCIM uses the team's default connection: the active connection marked Set as default connection, or, if none is marked, the oldest active one. Its Default role and Default environments are what every provisioned person starts with.

If the team has no active connection, or the default connection's role is Member and it has no default environments, every user your IdP tries to create fails with 400:

Cannot provision user: configure SSO connection default environments first

Also verify your email domain on the connection (see Add and verify your email domain). SCIM creates the Truto account, and SSO is how the person then signs in. SSO signs people in only on a verified domain.

1. Generate a SCIM token

1. Open Settings → SCIM (app.truto.one/settings/scim).

2. Under SCIM endpoint, copy the SCIM Base URL:

   https://api.truto.one/scim/v2

3. Under Bearer token, click Generate token, then Generate SCIM Token.

4. Copy the token into your IdP now. Truto shows it only once and stores only a hash of it. Tick I have copied my SCIM token shown above and click Done.

Your IdP sends this token as Authorization: Bearer <SCIM token> on every SCIM request. The token is tied to this team.

To make sure the token works, call the service provider config endpoint:

curl https://api.truto.one/scim/v2/ServiceProviderConfig \
  -H "Authorization: Bearer <SCIM token>"

To revoke the token, click Revoke token under Bearer token. Provisioning stops until you generate a new token and put it in your IdP.

2. Configure your identity provider

In your IdP's SCIM settings for the Truto app (Okta, Microsoft Entra ID and other SCIM 2.0 clients), enter these values:

Truto doesn't sync passwords. People sign in with SSO.

Your IdP can look up people who already belong to your team before creating them. Truto answers this request:

curl --get https://api.truto.one/scim/v2/Users \
  --data-urlencode 'filter=userName eq "ada@example.com"' \
  -H "Authorization: Bearer <SCIM token>"

What Truto supports

Limits:

• Filters. Only eq is supported: userName eq "..." or externalId eq "..." on Users, and displayName eq "..." or externalId eq "..." on Groups.
• Pagination. Use startIndex (1-based) and count. count defaults to 100, and 100 is the maximum.
• Not supported: bulk operations, sorting, ETags and password changes.

Responses use Content-Type: application/scim+json. Errors use the SCIM error schema, with status and detail.

On a user, Truto reads these attributes:

• userName: the email address, stored in lowercase. Required, or Truto uses emails[0].value.
• name.formatted or displayName: the person's name. Without either, Truto uses the part of the email before the @.
• externalId
• active: Truto accepts true and false, as JSON booleans or as strings like Entra's "False".

A person's Truto user ID is their SCIM id. Group members refer to people by that id.

A Truto account belongs to one person across every team they're in. If the email your IdP sends already has an account in another Truto team, creating the user fails with 409 User already exists. Invite that person from Settings → Team members instead.

3. Map groups to roles and environments

Groups your IdP pushes appear under Group mapping on Settings → SCIM. The table has these columns:

Pick a role and environments for a group and click its save button. Choosing None deletes the group's mapping. Until your IdP pushes a group, the table shows No IdP groups synced yet.

Truto works out each person's access from all their mapped groups:

• Admin wins. If any of a person's groups maps to Admin, they're an admin of the team, with access to every environment.
• Environments add up. Otherwise they're a member with the union of the environments from all their mapped groups.
• Mappings replace connection defaults. For someone in at least one mapped group, the mappings decide their role and environments. The SSO connection's defaults don't apply on top, and environments no mapping grants are taken away.
• Members need an environment. A Member mapping needs at least one environment.
• Leaving every mapped group falls back. Someone who leaves all their mapped groups goes back to the default role and environments of the SSO connection they're linked to. If they aren't linked to one of this team's connections, they stay on the team as a member with no environments.
• The team keeps an admin. Truto refuses a mapping change that would leave no admin who can sign in. The API answers 409 with This change would leave the team with no admin. Make another member an admin first.

Truto recalculates access whenever your IdP changes a group's members and whenever you save a mapping.

To read groups and mappings from the API or the CLI:

truto scim-groups list --team-id <team_id>
truto group-mappings list --team-id <team_id>

# Groups your IdP has pushed, with member_count
curl "https://api.truto.one/scim-group?team_id=<team_id>" \
  -H "Authorization: Bearer <API token>"
 
# Group mappings
curl "https://api.truto.one/group-mapping?team_id=<team_id>" \
  -H "Authorization: Bearer <API token>"

Deprovisioning

When your IdP deactivates a person (active: false in a PUT or PATCH) or deletes them (DELETE /scim/v2/Users/<id>), Truto removes them from the team and from every environment of the team.

• The account stays. Truto doesn't delete it, and the person stays a member of any other Truto team they belong to.
• The person disappears from this team. A deactivation answers with the user and active: false. After that, GET /scim/v2/Users/<id> returns 404, and the person no longer appears in the user list.
• API tokens keep working. API tokens belong to an environment, not to the person who created them. Review Settings → API Tokens when someone leaves.

To bring someone back, set them to active: true in your IdP. Truto adds them back to the team only if their account belongs to no other team. They get the default connection's role and environments, plus whatever their mapped groups still grant. If their account belongs to another team, the request returns 404, and you need to invite them from Settings → Team members.

Under Sync status, Settings → SCIM shows how many people your IdP has synced and when it last provisioned.

API and CLI

truto scim-tokens list --team-id <team_id>

curl "https://api.truto.one/scim-token?team_id=<team_id>" \
  -H "Authorization: Bearer <API token>"

Next

SCIM relies on your SSO connection's defaults and verified domain. To change those, or to enforce SSO, see Single sign-on. To add people by hand instead, see Adding team members.