SCIM provisioning

NexBasira exposes a SCIM 2.0 endpoint at /api/scim/v2/ so your IdP can create, update, and deactivate users automatically when employees join, change roles, or leave the company. Per-org bearer-token auth, standard SCIM schemas, no surprises.

Before you start

SCIM is available on the Pro tier and above.
You already need SSO configured (see SSO setup). SCIM provisions users; SSO logs them in.
You need org_admin on the NexBasira side + permission to configure provisioning in your IdP.

Issue a SCIM token

In the SPA: Admin → SCIM provisioning token.
Click Issue token. The plaintext token is shown exactly once — copy it immediately.
Note the SCIM base URL shown above the button:
```
https://app.nexbasira.com/api/scim/v2/
```

The token authenticates every SCIM call as that org. It's scoped + revocable independently of API credentials and SSO config.

Wire your IdP

Microsoft Entra ID (Azure AD)

In the Entra admin centre, open your NexBasira Enterprise App.
Provisioning → Get started → Provisioning Mode: Automatic.
Tenant URL: https://app.nexbasira.com/api/scim/v2/
Secret Token: paste the token from NexBasira.
Click Test Connection. You should see "Tenant URL and Secret Token are valid".
Map attributes (defaults work for the common case). Save.
Assign users / groups + flip Provisioning Status to On.

Okta

In Okta, open your NexBasira app.
Provisioning → Configure API Integration → Enable API Integration.
Base URL: https://app.nexbasira.com/api/scim/v2/
API Token: paste the token.
Click Test API Credentials; expect "API token verified".
On the To App tab, enable Create / Update / Deactivate.
Assign users / groups.

OneLogin / Google Workspace / Keycloak

All similar: enable SCIM provisioning on the NexBasira app, paste the base URL + token, test, assign. The endpoint conforms to RFC 7644, so any SCIM 2.0-compliant IdP works.

What gets provisioned

The SCIM endpoint exposes the standard Users + Groups resources. We don't currently expose custom Org-side roles via SCIM Groups — role assignment after first sign-in is managed in the SPA. SCIM creates the user; you set the role.

Supported operations

Operation	Effect on NexBasira
POST /Users	Creates a User + Membership in your org with the configured default role.
PUT /Users/{id}	Updates the user's name + email + active flag.
PATCH /Users/{id}	Same — partial updates supported.
DELETE /Users/{id}	Soft-deactivates the membership (sets `active=false`). Audit-trail rows preserved.
GET /Users	Lists users in your org for IdP reconciliation.
GET /Users/{id}	Reads one user.
GET /Groups	Returns the four system roles + any custom roles, for visibility only.

Attribute mapping (defaults)

SCIM attribute	NexBasira field
`userName`	email (lowercased)
`emails[type=work].value`	email (fallback)
`name.givenName`	first_name
`name.familyName`	last_name
`active`	Membership.is_active
`externalId`	stored on Membership for IdP correlation

Filtering

The endpoint supports the SCIM filter query param on userName + externalId, which is what IdPs use for reconciliation:

GET /api/scim/v2/Users?filter=userName eq "alice@acme.com"
GET /api/scim/v2/Users?filter=externalId eq "azure-uid-12345"

More complex filters (and, or, co, etc.) aren't required by IdP integrations in our experience. Open a ticket if you hit a case.

Rotating the token

On the SCIM card in the SPA admin, click Rotate token. The plaintext is shown once + the old token is revoked immediately. Update your IdP with the new token before the next provisioning sweep or provisioning will start failing.

Revocation

Click Revoke on the SCIM card to immediately invalidate the active token. SCIM provisioning stops; existing users + memberships are untouched. Issue a new token to resume.

What this doesn't do

Doesn't grant API access — that's cvp_pub/cvp_sec.
Doesn't drive RBAC role assignment — SCIM Groups expose roles read-only; assign roles in the SPA.
Doesn't replace SSO — users still need SSO (or a password) to actually sign in. SCIM creates the account shell.

What's next

SSO setup — pair SCIM with OIDC / SAML for the full IdP-driven flow
Security posture — token-at-rest hashing + audit logging for SCIM calls