Nullgap.dev Docs

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 400 sso_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

  1. Open Settings, Access, SCIM provisioning.
  2. Choose Turn on and create a token.
  3. Copy the token. It is shown once. Nullgap stores only a hash of it and cannot show it again.
  4. In your identity provider, enter the SCIM base URL and the token (see set-up notes).
ValueWhat it is
SCIM base URL$NULLGAP_URL/api/scim/v2. Your provider may call it the tenant URL or the SCIM connector base URL
TokenStarts 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

EndpointSupported
GET /ServiceProviderConfig, GET /ResourceTypes, GET /SchemasYes. They describe the one resource type, User
GET /UsersYes, with filtering and paging
GET /Users/:idYes
POST /UsersYes. Answers 201
PUT /Users/:idYes
PATCH /Users/:idYes: add, replace and remove operations
DELETE /Users/:idYes. Answers 204
GET /GroupsAnswers 200 with an empty list (totalResults 0)
POST /GroupsAnswers 501: "Group provisioning is not supported..."
Any other /Groups requestNot routed. There is no group resource
FeatureSupported
PATCHYes
FilteringYes, as described below
Bulk operationsNo
SortingNo
ETagsNo
Changing passwordsNo. 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.

FilterMatches
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 attributeUsed forNotes
userNameThe person's identityRequired. 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
emailsThe address, when userName is not oneNullgap takes the entry marked primary, else the one of type work, else the first
externalIdStored and returnedYour provider's own id for the person
name.givenName, name.familyNameStored and returnedname.formatted is derived and read-only
displayNameStored and returnedUsed as the name of a new Nullgap account
activeMembershiptrue 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 providerEffect in Nullgap
Create a user, or set active to trueThe 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 IDThe SCIM record is updated. Nothing else changes
Change the addressThe membership moves: the account for the old address loses it, the account for the new address gains it
Set active to falseSee deactivation below
Delete the userSee deletion below
PUT without activeTreated 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.deprovisioned to 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 settingWhat to enter
SCIM version2.0
Base URL, tenant URL or connector URLThe SCIM base URL from the console
AuthenticationHTTP header, bearer token (sometimes "OAuth bearer token" or "secret token"): the SCIM token
Unique identifier for usersuserName
User name mappingThe 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 actionsCreate users, update user attributes, deactivate users. Turn off group push and password sync
Deprovisioning behaviourEither "deactivate" or "delete" works. Prefer deactivate if you want returning people to get their old role back

Then:

  1. Run your provider's connection test. It usually calls GET /Users with a filter, which must answer 200.
  2. Assign one test person and check that they appear under People and that the audit log shows member.provisioned.
  3. Unassign them and check that they are gone and the audit log shows member.deprovisioned.
  4. Assign the real groups.

#When something goes wrong

AnswerMeaningWhat 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 offIssue 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 domainsSet up single sign-on again
400 invalidValue "Email domain ... is not one this organisation allows"The address is on another domainAdd the domain, or fix the user name mapping
400 invalidValue "Email domain ... has not been verified in Nullgap..."The domain is listed but not verifiedVerify it, then provision again
400 invalidValue "userName or a primary email must be an email address"Neither userName nor emails holds an addressFix the attribute mapping
400 mutabilityThe person is an ownerSee owners are never removed
409 uniquenessA SCIM user with that userName already existsLet your provider match the existing user instead of creating one
400 invalidFilterA filter Nullgap does not supportUse one of the filters above
501 on /GroupsGroup push is onTurn it off

A refused request changes nothing: memberships are checked before anything is saved.

Nullgap documentation