SCIM provisioning & attribute mapping #
SCIM 2.0 keeps your eCardWidget team-member directory in sync with your IdP automatically: when someone is added, changed, or deactivated in Okta/Entra/etc., the change is pushed to ECW. SCIM is receive-only — ECW never writes back to your IdP.
SCIM provisions team members, not login users. Team members are the people your organization celebrates/manages in ECW; they don't sign into ECW. Login is a separate channel (SSO).
Prerequisites #
- SSO configured and your email domain verified first.
- Enterprise plan.
1. Generate the SCIM token in ECW #
- Settings → SSO & Directory Sync → Directory Sync tab → Enable SCIM.
- Click Save & Generate SCIM Token → copy it now (it's shown once). Store it in your IdP's secrets manager.
The token does not expire. Directory sync keeps working indefinitely — you'll never be surprised by a token that lapses. The dashboard shows when the token was last used so you can spot a stale or unused one, and sends a single, optional "consider rotating" reminder once the token passes ~12 months old (informational only — sync is never interrupted).
To rotate (recommended periodically, or any time it may have been exposed): click Regenerate SCIM Token. The previous token keeps working for 48 hours, so you can paste the new one into your IdP with no downtime. Regenerating (or turning SCIM off) immediately revokes access — that's your kill switch if a token leaks.
2. Point your IdP at the right SCIM URL #
ECW's SCIM tab shows two URLs. Which one to use depends on the IdP:
| IdP | Use | URL |
|---|---|---|
| Okta | SCIM Base URL (Okta appends /Users) |
https://app.ecardwidget.com/v2/api/scim/v2 |
| Microsoft Entra ID | Users Endpoint URL (full) | https://app.ecardwidget.com/v2/api/scim/v2/Users |
| Google Workspace | Users Endpoint URL (full) | https://app.ecardwidget.com/v2/api/scim/v2/Users |
| Other | Whichever your connector expects | base or /Users |
Auth: Authorization: Bearer <SCIM token> on every request.
Then enable, at minimum: Create Users, Update User Attributes, Deactivate Users. Leave password sync off (team members have no login).
3. Provisioning lifecycle — what to expect #
| IdP action | ECW result |
|---|---|
| Assign / create user | New team member row, tagged source = SSO (🔵 badge), with the IdP's user id stored |
| Update attribute | The mapped ECW field updates (usually within ~60s) |
| Deactivate | Team member marked disabled — the row is kept (preserves eCard history), not deleted |
| Reactivate | disabled flips back off |
4. Attribute mapping (custom field matching) #
ECW ships with sensible default mappings from standard SCIM attributes to ECW's team-member fields, and lets you override any of them per account in the Attribute Mappings tab.
Default mappings #
| ECW field | Default SCIM source(s) — first match wins |
|---|---|
| First name | name.givenName, givenName |
| Last name | name.familyName, familyName |
userName, emails[primary].value, emails[0].value |
|
| Display name | displayName |
| Preferred name | (nickname / preferred-name attributes) |
| Job title | title (SCIM Enterprise extension) |
| Department | department (Enterprise) |
| Employee ID | employeeNumber (Enterprise) |
| Manager | manager.value (Enterprise) — resolved to an ECW team member in the same account |
| Hire date | hireDate |
| Birthday | birthdate (stored with a privacy year) |
| Anniversary | (custom date attribute) |
| Active / disabled | active |
Notes on the special transforms:
- Manager is resolved to a team member in your account only — a manager value pointing at someone outside your tenant is ignored (no cross-tenant linking).
- Department is looked up (or created) in your ECW department list.
- Birthday is stored with a fixed privacy year so age isn't retained.
Discover what your IdP actually sends, then map it #
The Attribute Mappings tab includes attribute discovery: as your IdP pushes users, ECW records every attribute path it receives with a sample value, its type, and whether it's already mapped. Use it to:
- See exactly what keys your IdP sends (vendors differ — e.g. custom Enterprise-extension paths).
- Point an ECW field at the right source path when the default doesn't match your IdP's shape.
- Catch mapping errors (values that arrived but couldn't be applied).
To customize: open Attribute Mappings, pick the ECW field, and set the source path(s) in priority order (first non-null wins). Your overrides replace the default sources for that field only; unmapped fields keep their defaults.
Group-based sync filtering is best-effort with Okta/Entra. Those IdPs push group membership in a separate call after creating the user, so groups are usually empty on the initial create. If you gate provisioning on group membership, prefer department-based filtering (department is reliably present on every create), or use the OIDC JIT path.
5. The IdP is the source of truth (field locking) #
For team members with source = SSO, the fields your IdP manages are read-only in the ECW UI (editing them returns a "managed by your identity provider" error):
first name, last name, email, employee ID, department, job title, manager, hire date, birthday, and the external IdP id.
Fields ECW owns stay editable — custom celebration dates, sort order, profile image, the manager flag, and the disabled toggle — so admins can still set custom celebrations and override availability. Attempting to change a SCIM-managed member's email in ECW is rejected (change it at the IdP instead).
SCIM API reference #
ECW implements SCIM 2.0 (RFC 7644):
| Method | Path | Purpose |
|---|---|---|
GET |
/v2/api/scim/v2/Users |
List / filter |
GET |
/v2/api/scim/v2/Users/<id> |
Get one |
POST |
/v2/api/scim/v2/Users |
Create |
PATCH |
/v2/api/scim/v2/Users/<id> |
Partial update |
PUT |
/v2/api/scim/v2/Users/<id> |
Full replace |
DELETE |
/v2/api/scim/v2/Users/<id> |
Deactivate (soft) |
POST |
/v2/api/scim/v2/Bulk |
Bulk (up to 1000 operations) |
Limits: request body 10 MB (larger → 413); bulk 1000 operations (more → 413). The
bearer token does not expire — it's revoked only by Regenerate SCIM Token or by disabling
SCIM (a revoked/unknown token → 401).
Troubleshooting (SCIM) #
| Symptom | Fix |
|---|---|
| Test connection "Invalid user ID" (Okta) | You pasted the base URL with /Users. Use the base URL; Okta appends /Users. |
401 on every request |
Token wrong or revoked (regenerated / SCIM disabled), or wrapped in extra quotes when pasted. Regenerate and re-paste. |
413 Payload Too Large |
Body over 10 MB or bulk over 1000 ops. Split the batch. |
422 "email cannot be changed" |
Editing email on a SCIM-managed member. Change it at the IdP (via userName). |
403 "does not match sync filter" |
Working as intended — the user was filtered out by your sync filter. |
| Attribute not landing | Open Attribute Mappings → discovered attributes to see what the IdP actually sent, and check mapping errors. |
More: Troubleshooting.