SCIM user provisioning

EmbayLMS supports SCIM 2.0 (System for Cross-domain Identity Management) so your identity provider — Okta, Microsoft Entra ID (Azure AD), or any SCIM-2.0 client — can create, update, and deactivate EmbayLMS user accounts automatically, keeping them in sync with your HR system.

When an employee is onboarded in your IdP, the IdP provisions an EmbayLMS account. When their attributes change (name, role), the IdP pushes the update. When they are offboarded, the IdP deactivates the account in EmbayLMS — the learning record is preserved, not deleted.

SCIM vs. SSO: SCIM manages accounts (provisioning). SAML/OIDC manages logins (authentication). They are independent — you can run either alone, but most organizations run SCIM alongside SAML or OIDC so accounts are both auto-created and SSO-enabled.

Base endpoint

SCIM is served per-tenant on your own subdomain. The base URL is:

https://<your-tenant>.embaylms.com/api/v1/scim/v2

Two resource endpoints are implemented:

All requests authenticate with a Bearer token (see Step 1) and the tenant is resolved automatically from the subdomain.

Step 1 — Generate a SCIM bearer token

1. In EmbayLMS, go to Admin → Settings → User Management → SCIM.
2. Click Create token, enter a label (e.g. “Okta production”), and create it.
3. The token is shown only once in a reveal banner. Copy it immediately — it cannot be retrieved again. Only a short prefix is stored for identification.
4. The page also shows the SCIM base path (/api/v1/scim/v2) for reference.

You can create multiple tokens (e.g. one per IdP) and revoke any of them at any time from the same page; the list shows each token’s label, prefix, creation date, and last-used date. Revoking a token immediately stops provisioning for any IdP using it.

Tokens are stored as a SHA-256 hash. EmbayLMS never stores or displays the raw token after creation.

Step 2 — Supported operations and attributes

Users (/Users)

User attribute mapping — SCIM attributes map to EmbayLMS user fields as follows:

Groups (/Groups)

Group attribute mapping:

Step 3 — Matching logic and deprovisioning

Matching (create vs. update). On a user POST, EmbayLMS first looks for an existing user by externalId. If one is found, that user is updated in place (email, name, role, active) rather than duplicated. If no externalId match exists, it checks for an existing user with the same email — if that email is already taken, the request returns 409 Conflict; otherwise a new user is created. Groups follow the same pattern, matched by externalId.

Recommendation: always send a stable externalId from your IdP. It is the key that lets EmbayLMS recognize the same person across syncs (including after an email change), which prevents duplicate accounts.

Deprovisioning. EmbayLMS does not hard-delete users via SCIM. When your IdP unassigns or deactivates a user, send active: false (via PATCH, PUT, or DELETE). The account is deactivated: the user can no longer sign in, but their completions, certificates, and transcript are retained for compliance. Re-sending active: true reactivates the same account with its history intact.

Audit. Every SCIM create and update is written to the EmbayLMS audit log (actor system, role scim) for SOC 2 evidence.

Step 4 — Worked example: configure Okta

1. In the Okta Admin Console, go to Applications → Browse App Catalog, add a SCIM 2.0 Test App (or your existing EmbayLMS SAML app if it supports provisioning), then open its Provisioning tab and click Configure API Integration.

2. Enter the SCIM connector settings:

   Okta field	Value
   SCIM connector base URL	https://<your-tenant>.embaylms.com/api/v1/scim/v2
   Unique identifier field for users	userName
   Authentication Mode	HTTP Header
   Authorization	Bearer <token from Step 1>
   Supported provisioning actions	Push New Users, Push Profile Updates, Push Groups

3. Click Test API Credentials — Okta calls GET /Users to verify the token.

4. Under Provisioning → To App, enable Create Users, Update User Attributes, and Deactivate Users.

5. Map Okta profile attributes to SCIM: userName → email, givenName, familyName, and (optionally) a roles mapping to one of learner, author, manager, admin.

6. Assign people/groups to the app. Okta provisions them into EmbayLMS; unassigning a user sends active: false, which deactivates the account.

Entra ID (Azure AD): the flow is equivalent — add the Enterprise application → Provisioning, set Provisioning Mode to Automatic, paste the same base URL as the Tenant URL and the token as the Secret Token, then Test Connection and start provisioning.

Configuration reference

Troubleshooting