SCIM v2 User Provisioning

SCIM (System for Cross-domain Identity Management) v2 lets your IdP push user lifecycle events directly into Mittr. Pair it with SAML SSO and your team’s Mittr access becomes fully managed by HR:

HR adds Alice to the mittr-users group in Okta → she appears in Mittr’s Team tab, ready to sign in via SSO.
HR removes Alice when she leaves → she’s deactivated in Mittr, existing sessions invalidated on next request.
Alice changes her name or title → Mittr reflects it on next sync.

No manual invites, no offboarding checklist to forget, no ex-employees retaining access. Standard enterprise procurement requirement and available on the Scale plan.

How it relates to SAML

SAML authenticates: it proves a user is who they say they are when they sign in.

SCIM provisions: it pre-creates (or deactivates) the user record so when they show up to sign in, Mittr already knows they exist (or rejects them outright).

Most enterprises buy these as a bundle. You can use SAML without SCIM (invite users manually, let JIT create them on first login) and you can use SCIM without SAML (use password auth, with admins triggering password resets), but the combo is the zero-touch path.

Prerequisites

Scale plan or above.
Admin role in Mittr.
Your IdP must support SCIM 2.0. All major vendors (Okta, Azure AD, Google Workspace, OneLogin, Rippling, JumpCloud) do.

Step 1: Issue a SCIM token in Mittr

Sign into Mittr.
Go to Settings → SSO → Provisioning (SCIM v2).
Click New token.
Give it a recognisable name (Okta production, Azure staging).
Mittr shows the token exactly once in a reveal drawer. Copy it now. Subsequent views only show the scim_a1b2c3d4… prefix.

The panel also shows your SCIM base URL: the other value your IdP needs. It looks like:

https://yourdomain.com/scim/v2

Step 2: Configure the IdP connector

Okta

In Okta, open the SAML app you created for Mittr (see the SAML guide: you need SAML configured first for the same app).
Open Provisioning → Configure API Integration.
Check Enable API integration.
Fill in:
- Base URL → https://yourdomain.com/scim/v2
- API Token → the token you copied in Step 1
Click Test API Credentials: should succeed.
Save. Okta surfaces a To App settings page:
- Check Create Users, Update User Attributes, Deactivate Users.
- Under Attribute Mappings, keep Okta’s defaults (userName, name, emails).
Push Groups → pick the groups whose members should be provisioned (e.g. mittr-engineers). Okta will now push every member of those groups into Mittr.

Azure AD (Microsoft Entra ID)

In the Enterprise application you created for Mittr SAML, open Provisioning.
Set Provisioning Mode to Automatic.
Under Admin Credentials:
- Tenant URL → https://yourdomain.com/scim/v2
- Secret Token → the token from Step 1
Click Test Connection: expect a green check.
Save. Default Mappings are fine. You can customise them under Mappings → Provision Azure Active Directory Users.
Under Settings, set Scope to “Sync only assigned users and groups” (recommended) or “Sync all users and groups”.
Toggle Provisioning Status to On.

Google Workspace

Google’s SCIM support is gated behind their Cloud Identity Premium / Enterprise tier. If available:

In the Admin console, go to Apps → Web and mobile apps → [your Mittr app] → Auto-provisioning.
Follow the wizard; at the credentials step, provide:
- SCIM endpoint → https://yourdomain.com/scim/v2
- Token → the SCIM token from Step 1
Map attributes, choose which directory units sync, save.

Other IdPs

Any SCIM 2.0-conformant IdP works. These are the endpoints it will hit:

Method	Path	Purpose
`GET`	`/scim/v2/ServiceProviderConfig`	Capability discovery (probed first)
`GET`	`/scim/v2/Users`	List with `filter`, `startIndex`, `count`
`POST`	`/scim/v2/Users`	Create user
`GET`	`/scim/v2/Users/{id}`	Fetch one
`PATCH`	`/scim/v2/Users/{id}`	Update or deactivate
`DELETE`	`/scim/v2/Users/{id}`	Soft-delete (status=disabled, row kept)

Auth is Authorization: Bearer <your-token>. Content-Type is application/scim+json.

What gets synced

Every user Okta/Azure/Google assigns to the SCIM app (directly or via group membership) appears in Mittr’s Team tab as an active member. The attribute mapping:

SCIM attribute	Mittr column
`userName`	`users.email`
`name.formatted`	`users.name` (preferred when set)
`name.givenName` + `name.familyName`	Combined into `users.name` as a fallback
`active: true`	`users.status = active`, `is_active = true`
`active: false`	`users.status = disabled`, `is_active = false`

Role: SCIM-provisioned users get the default role from your tenant’s active SAML SSO config (usually viewer). Promote them via the dashboard if needed. Group-based role mapping is roadmap for a future SCIM version; for now, roles are set after provisioning.

Deactivation: when the IdP sends PATCH { active: false } (user disabled, group membership removed, or DELETE), Mittr soft-deletes. The row survives with status = disabled, existing sessions are rejected on next request, and the audit history stays intact.

What doesn’t sync

Groups: Mittr doesn’t currently expose /scim/v2/Groups. If your IdP tries Group operations, they silently fail (most IdPs auto-detect this via ServiceProviderConfig and switch to Users- only mode).
Passwords: SCIM password attribute is ignored. SCIM- provisioned users authenticate via SAML, not password. If a user needs password access, an admin can send them a reset link from the dashboard.
Customisations: Mittr’s API keys, endpoints, events, etc. are tenant-level, not user-level. SCIM doesn’t touch them.

Testing your SCIM integration

The fastest way to verify your setup is working (before pointing real humans at it):

# Replace with your values
TOKEN=scim_your_token_here
BASE=https://yourdomain.com/scim/v2

# 1. Discovery: what most IdPs hit first
curl -sS $BASE/ServiceProviderConfig \
  -H "Authorization: Bearer $TOKEN" | jq

# 2. List users (empty initially)
curl -sS $BASE/Users \
  -H "Authorization: Bearer $TOKEN" | jq

# 3. Create a test user
curl -sS -X POST $BASE/Users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[email protected]",
    "name": {"givenName": "Alice", "familyName": "Test"},
    "emails": [{"value": "[email protected]", "primary": true}],
    "active": true
  }' | jq

# 4. Head to your Mittr dashboard Team tab: alice should appear.

Rotating a SCIM token

In Settings → SSO → Provisioning, find the token you want to rotate. Click the trash icon to revoke it. Rows survive for audit but subsequent IdP requests will 401.
Issue a fresh token and paste it into your IdP’s SCIM config.

Do this in the same session when possible: between revocation and re-configuration your IdP’s sync will fail, which is tolerated but generates noise in your IdP’s provisioning logs.

Troubleshooting

IdP reports “401 Unauthorized” on every sync

The bearer token is either wrong, revoked, or for a different workspace.

Re-check the token in the IdP config (watch out for whitespace on paste).
In Settings → SSO → Provisioning, verify the token is Active (not Revoked). Check the Last used column: it should update on each IdP sync attempt.

IdP reports “409 Conflict” when trying to create a user

The user already exists with that email in your Mittr tenant. Expected SCIM behaviour. Your IdP should switch to PATCH and update the existing user. If it doesn’t, check the IdP’s “on conflict” policy.

Users appear as `scim-provisioned` but can’t log in

SCIM provisions; SAML authenticates. If the user has no password (SCIM doesn’t set one) and SAML isn’t configured for your workspace, they literally can’t sign in. Fix: configure SAML (see SAML guide).

Deactivated users still see stale dashboards

Deactivation invalidates sessions at next validation, not instantaneously. Active dashboards may render one more time until their next API call triggers a 401. In practice this is under a minute of staleness.

`filter` queries return fewer results than expected

Mittr supports a conservative filter subset:

userName eq "foo@bar"
emails eq "foo@bar"

Anything else is silently treated as “no filter” (returns all users). Most IdPs only use the supported forms; if yours sends more exotic filters, the IdP’s de-duplication might get fuzzy but create remains idempotent (returns 409 on duplicates).

Under the hood

For engineers curious about internals:

Tokens stored as SHA-256 hex digests (never plaintext).
Per-tenant bearer: each token authenticates to exactly one workspace.
Soft-delete model: DELETE /Users/{id} flips status=disabled, doesn’t remove the row.
Idempotent create: POST /Users with a duplicate email returns 409 with scimType: "uniqueness" per RFC 7644 §3.12.
User-merge on SAML login: if a SCIM-provisioned user later signs in via SAML, their existing row gets the SSO identity attached (no duplicate created).

Next steps

Layer SAML on top if you haven’t: SAML guide.
Lock down the API: for defense-in-depth, combine SCIM-pushed identities with IP whitelisting so even a leaked token can’t be used from outside your corp network.