Administration
SCIM provisioning
Let your identity provider add, update, deactivate and remove Nullgap members automatically with SCIM 2.0.
SCIM lets your identity provider manage who is a member of your organisation in Nullgap. When someone is assigned to the Nullgap application they become a member; when they are unassigned or leave, they lose access.
Nullgap implements SCIM 2.0 for users only. Groups are not provisioned.
#Before you start
- You must be an owner to turn provisioning on, replace the token or turn it off. Admins can see the status.
- Single sign-on must be saved with at least one allowed e-mail domain. Provisioning only accepts addresses on those domains. Without it, issuing a token is refused with
400sso_first. - Each domain must be verified before SCIM can add people on it.
- Issuing a token asks for a fresh second-factor check if your account has a second factor. See the step-up check.
#Turn it on
- Open Settings, Access, SCIM provisioning.
- Choose Turn on and create a token.
- Copy the token. It is shown once. Nullgap stores only a hash of it and cannot show it again.
- In your identity provider, enter the SCIM base URL and the token (see set-up notes).
| Value | What it is |
|---|---|
| SCIM base URL | $NULLGAP_URL/api/scim/v2. Your provider may call it the tenant URL or the SCIM connector base URL |
| Token | Starts with ngscim_. Sent as Authorization: Bearer followed by the token |
The token belongs to one organisation and works only on the SCIM endpoints. It is not an API key and cannot call the rest of the API.
#Replacing the token and turning SCIM off
- Replace token issues a new token. The old one stops working immediately. Provisioning pauses until the new token is in your identity provider. Members are not affected.
- Turn off deletes the token. Your identity provider can no longer add or remove members. Everyone it added stays a member until you remove them.
If you lose the token, replace it.
#Checking the status
An API key with the admin scope can read the status. Issuing and deleting the token is console-only.
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/scim"
{
"enabled": true,
"baseUrl": "https://nullgap.acme.example/api/scim/v2",
"tokenCreatedAt": "2026-11-16T09:30:00.000Z",
"tokenLastUsedAt": "2026-11-16T10:02:00.000Z",
"users": 42,
"activeUsers": 40
}
tokenLastUsedAt is updated at most once a minute. users counts the SCIM user records your provider has created here; activeUsers counts those that are active.
#What is supported
| Endpoint | Supported |
|---|---|
GET /ServiceProviderConfig, GET /ResourceTypes, GET /Schemas | Yes. They describe the one resource type, User |
GET /Users | Yes, with filtering and paging |
GET /Users/:id | Yes |
POST /Users | Yes. Answers 201 |
PUT /Users/:id | Yes |
PATCH /Users/:id | Yes: add, replace and remove operations |
DELETE /Users/:id | Yes. Answers 204 |
GET /Groups | Answers 200 with an empty list (totalResults 0) |
POST /Groups | Answers 501: "Group provisioning is not supported..." |
Any other /Groups request | Not routed. There is no group resource |
| Feature | Supported |
|---|---|
| PATCH | Yes |
| Filtering | Yes, as described below |
| Bulk operations | No |
| Sorting | No |
| ETags | No |
| Changing passwords | No. Nullgap has no passwords |
Every endpoint needs the token, including the discovery endpoints. All paths are relative to the base URL. Answers use application/scim+json.
#Groups
Nullgap has no groups to map. To provision by group, assign the group to the Nullgap application at your identity provider: the provider then pushes that group's members as individual users.
Turn "push groups" off in your provider. If it is on, the empty group list tells the provider that no groups exist, and its attempt to create one gets the 501 above. Users are not affected by that error.
Roles cannot be set through SCIM. Everyone who is added gets the Role for new members from the single sign-on settings. Change a person's role in Nullgap afterwards, under People.
#Filters and paging
GET /Users accepts one filter form: an attribute, eq, and a quoted value.
| Filter | Matches |
|---|---|
userName eq "dana@acme.example" | The user name, ignoring case |
externalId eq "00u1abcd" | The external ID, exactly |
id eq "scu_9x2k" | The Nullgap SCIM id, exactly |
emails.value eq "dana@acme.example" | The same as userName, ignoring case |
emails[type eq "work"].value eq "dana@acme.example" | The same as userName, ignoring case |
Any other attribute, operator (co, sw, and, or) or form answers 400 with scimType invalidFilter.
Paging uses startIndex (from 1) and count. A page holds at most 200 users, which is also the default. Results are ordered by creation time.
#Attribute mapping
| SCIM attribute | Used for | Notes |
|---|---|---|
userName | The person's identity | Required. Unique within the organisation: a second user with the same name gets 409 uniqueness. If it is an e-mail address, it is the address Nullgap uses |
emails | The address, when userName is not one | Nullgap takes the entry marked primary, else the one of type work, else the first |
externalId | Stored and returned | Your provider's own id for the person |
name.givenName, name.familyName | Stored and returned | name.formatted is derived and read-only |
displayName | Stored and returned | Used as the name of a new Nullgap account |
active | Membership | true means a member, false means no membership |
Anything else your provider sends (title, addresses, the enterprise extension, and so on) is accepted and not kept.
The address must be on one of the organisation's allowed domains, and that domain must be verified. Otherwise the request answers 400 with scimType invalidValue and nothing is changed.
SCIM decides which Nullgap account a SCIM user maps to, and whether that account is a member. It never edits the account itself: a person's name on their profile and their sign-in methods are theirs.
#An example
A request your identity provider might send:
POST /api/scim/v2/Users
Authorization: Bearer ngscim_...
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "dana@acme.example",
"externalId": "00u1abcd",
"name": { "givenName": "Dana", "familyName": "Okafor" },
"active": true
}
The answer, with status 201:
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "scu_9x2k",
"externalId": "00u1abcd",
"userName": "dana@acme.example",
"name": { "givenName": "Dana", "familyName": "Okafor", "formatted": "Dana Okafor" },
"displayName": "",
"emails": [{ "value": "dana@acme.example", "type": "work", "primary": true }],
"active": true,
"meta": {
"resourceType": "User",
"created": "2026-11-16T09:30:00.000Z",
"lastModified": "2026-11-16T09:30:00.000Z",
"location": "https://nullgap.acme.example/api/scim/v2/Users/scu_9x2k"
}
}
Errors use the SCIM error form:
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"status": "400",
"detail": "Email domain other.example is not one this organisation allows",
"scimType": "invalidValue"
}
#What each action does
| Action from the identity provider | Effect in Nullgap |
|---|---|
Create a user, or set active to true | The person becomes a member with the role for new members. A Nullgap account is created for the address if none exists. Someone who is already a member keeps their role. Audit event: member.provisioned |
| Update name or external ID | The SCIM record is updated. Nothing else changes |
| Change the address | The membership moves: the account for the old address loses it, the account for the new address gains it |
Set active to false | See deactivation below |
| Delete the user | See deletion below |
PUT without active | Treated as active: true, because PUT replaces the whole user |
#Deactivation and deletion
Deactivating a user (active: false):
- removes the person's membership of the organisation;
- releases their review seat;
- ends that person's single sign-on sessions for the organisation;
- keeps the SCIM record, with the role the person had, so that reactivating them later gives the same role back;
- writes
member.deprovisionedto the audit log.
Deleting a user does the same and also deletes the SCIM record, so the remembered role is gone. If your provider creates the person again later, they join with the role for new members. The audit log records scim.user_deleted.
Neither action deletes the person's Nullgap account. Sessions the person started another way are not ended, but without a membership they can no longer open the organisation.
Taking access away always works, even for a domain whose verification has lapsed. Adding or reactivating someone needs a verified domain.
#Owners are never removed
A request that would deactivate or delete an owner is refused with 400 and scimType mutability:
Owners cannot be deactivated or removed through SCIM. Change their role in Nullgap first.
Nothing is changed by such a request. This stops a compromised identity provider or a leaked token from removing the people who can repair the set-up. To offboard an owner, make someone else an owner, change the leaver's role under People, and let your provider deactivate them.
#Set-up notes for your identity provider
Field names differ between providers. In general terms:
| Provider setting | What to enter |
|---|---|
| SCIM version | 2.0 |
| Base URL, tenant URL or connector URL | The SCIM base URL from the console |
| Authentication | HTTP header, bearer token (sometimes "OAuth bearer token" or "secret token"): the SCIM token |
| Unique identifier for users | userName |
| User name mapping | The person's e-mail address on one of your allowed domains. If your directory's sign-in names are not e-mail addresses on those domains, map the mail attribute to userName, or make sure a primary e-mail is sent in emails |
| Supported actions | Create users, update user attributes, deactivate users. Turn off group push and password sync |
| Deprovisioning behaviour | Either "deactivate" or "delete" works. Prefer deactivate if you want returning people to get their old role back |
Then:
- Run your provider's connection test. It usually calls
GET /Userswith a filter, which must answer200. - Assign one test person and check that they appear under People and that the audit log shows
member.provisioned. - Unassign them and check that they are gone and the audit log shows
member.deprovisioned. - Assign the real groups.
#When something goes wrong
| Answer | Meaning | What to do |
|---|---|---|
401 "A SCIM bearer token is required" | No token, or a token that is not a SCIM token (an API key, for example) | Send the ngscim_ token as a bearer token |
401 "That SCIM token is not valid" | The token was replaced or SCIM was turned off | Issue a new token and update your provider |
400 "Single sign-on with allowed email domains must be configured..." | Single sign-on was removed or has no domains | Set up single sign-on again |
400 invalidValue "Email domain ... is not one this organisation allows" | The address is on another domain | Add the domain, or fix the user name mapping |
400 invalidValue "Email domain ... has not been verified in Nullgap..." | The domain is listed but not verified | Verify it, then provision again |
400 invalidValue "userName or a primary email must be an email address" | Neither userName nor emails holds an address | Fix the attribute mapping |
400 mutability | The person is an owner | See owners are never removed |
409 uniqueness | A SCIM user with that userName already exists | Let your provider match the existing user instead of creating one |
400 invalidFilter | A filter Nullgap does not support | Use one of the filters above |
501 on /Groups | Group push is on | Turn it off |
A refused request changes nothing: memberships are checked before anything is saved.
Nullgap documentation