User provisioning with SCIM

Your identity provider (IdP) can add people to your Appbricx workspace when you assign them, update their profile, and take their access away the moment you unassign or deactivate them. Appbricx speaks SCIM 2.0, the standard Okta, Microsoft Entra ID (Azure AD) and OneLogin use. Available on the Enterprise plan.

Before you start: verify your domain

SCIM only adds people whose email is on one of the workspace's verified email domains, the same DNS-verified domains single sign-on uses. That stops a workspace from pulling in someone else's Appbricx account without their consent. Add and verify your domain under Workspace settings → Single sign-on → Email domains first; until one is verified, you can't create a SCIM token.

Both the email and an email-shaped userName must be on a verified domain. Matching ignores case and is exact: eng.acme.com is a separate domain from acme.com, as it is for SSO.
Anyone else is refused with a 400 (scimType: "invalidValue"), and nothing is created or linked. The same applies to a PUT or PATCH that moves someone to another domain, and to reactivating them.
Deactivating and deleting always work.

What gets synced

Assign someone: Appbricx links the account with that email, or creates one, and adds it to the workspace as a member. Someone who is already in the workspace keeps their role.
Deactivate or unassign (active: false): they are removed from the workspace at once. Their Appbricx account stays, because it may belong to other workspaces. Reactivating brings them back with the role they had.
Delete: the same as deactivating, and Appbricx forgets the IdP record.
Groups set roles. A pushed group whose name ends in Admins, Members or Viewers (for example "Appbricx Admins") gives its members that role; the highest one wins. Any other group name leaves roles alone. People in no role group are members.
Name and email changes are kept on the provisioning record. The email someone signs in with is never changed by the IdP.

To let people sign in through your IdP as well, set up single sign-on on the same settings screen. SCIM decides who is in the workspace; SSO decides how they sign in.

Turn it on in Appbricx

Open Workspace settings → Single sign-on and scroll to User provisioning (SCIM). You need to be an admin or the owner.
Make sure your email domain is verified (see above), then copy the SCIM base URL. On Appbricx cloud it is https://www.appbricx.com/api/scim/v2.
Click Create token and copy the token (it starts with apx_scim_). It is shown once; Appbricx stores only a hash. SCIM is on while a token is active.

Who creates the token matters. A token the workspace owner creates can also remove admins and change roles from groups. A token an admin creates can add and remove members, but not admins, and it stores groups without changing roles. The owner can never be deactivated, removed or re-roled through SCIM, whoever made the token.

Okta

In the Okta admin console, go to Applications → Create App Integration, pick SWA or SAML 2.0 (use the same app as your SSO integration if you have one), and on the General tab tick Enable SCIM provisioning.
On Provisioning → Integration, set:
- SCIM connector base URL: your SCIM base URL
- Unique identifier field for users: userName
- Supported provisioning actions: Push New Users, Push Profile Updates, Push Groups (and Import New Users and Profile Updates if you want to import existing members)
- Authentication Mode: HTTP Header, Bearer token = your SCIM token
Click Test Connector Configuration, then Save.
On Provisioning → To App, enable Create Users, Update User Attributes and Deactivate Users.
Assign people or groups on Assignments. To set roles, push groups named like "Appbricx Admins" on Push Groups.

Microsoft Entra ID (Azure AD)

In the Entra admin center, go to Enterprise applications → New application → Create your own application and choose Integrate any other application you don't find in the gallery (or open your existing SSO app).
Open Provisioning, set Provisioning Mode to Automatic, and enter:
- Tenant URL: your SCIM base URL
- Secret Token: your SCIM token
Click Test Connection, then Save.
Under Mappings → Provision Microsoft Entra ID Users, keep userPrincipalName → userName (or map mail if your UPNs are not email addresses) and the default Switch([IsSoftDeleted], …) → active mapping. Make sure emails[type eq "work"].value is mapped from mail.
Assign users and groups under Users and groups, set Provisioning Status to On and save. Entra runs a cycle about every 40 minutes; use Provision on demand to test one user straight away.

OneLogin and other IdPs

In OneLogin, add the SCIM Provisioner with SAML (SCIM v2 Enterprise) app, paste the SCIM base URL and the token as SCIM Bearer Token, enable provisioning, and map userName to the email. Any IdP that speaks SCIM 2.0 with bearer tokens works the same way.

Google Workspace only provisions to apps listed in its own catalog, so it can't push to a custom SCIM URL yet. With Google, use single sign-on, which adds people the first time they sign in, and remove leavers in the workspace members list.

Endpoints

Endpoint	Supports
`/Users`	GET with `filter` (`eq` on `userName`, `externalId`, `emails.value`, `id`, `active`, joined with `and`), `startIndex` and `count` (up to 200); POST
`/Users/:id`	GET, PUT, PATCH (add, replace, remove), DELETE
`/Groups`, `/Groups/:id`	The same, filtering on `displayName`; PATCH adds and removes members; `excludedAttributes=members`
`/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas`	Discovery

Not supported: bulk operations, sorting, ETags, password changes and /Me. Responses use application/scim+json and the SCIM error format, for example a 409 with scimType: "uniqueness" when a userName is already provisioned.

Limits and safety

A token works for one workspace only. A request can never read or change another workspace.
Each token may make 600 requests a minute; repeated bad tokens from one address are blocked for a minute. Both answer 429 with Retry-After.
The workspace's member limit still applies; a provision over the limit answers 403.
Every change and every token created or revoked is recorded, and the latest show under Activity in the SCIM settings.
If the workspace leaves the Enterprise plan, its tokens answer 403 until it is back on Enterprise. Nobody is removed.

Self-hosting

The SCIM base URL is NEXT_PUBLIC_API_URL + /scim/v2; set SCIM_BASE_URL to override it. SCIM_RATE_LIMIT_PER_MIN (default 600) sets the per-token limit and SCIM_AUTH_FAIL_LIMIT_PER_MIN (default 30) the failed-authentication budget per client address. Run the database migrations so the SCIM tables exist.

Troubleshooting

401: the token is wrong, revoked, or not an apx_scim_ token. Create a new one and update the IdP.
403 Enterprise plan: the workspace isn't on Enterprise.
400 "isn't a verified domain": the person's email or userName is on a domain the workspace hasn't verified. Verify it under Single sign-on, or map the work email.
400 "needs an email address": map an email to userName or to the work email.
400 mutability on deactivate: the person is the workspace owner, or an admin and the token was created by an admin.
Someone removed in Appbricx still shows as active in the IdP: SCIM only removes people when the IdP tells it to. Unassign them in the IdP, or deactivate and reactivate them to add them back.