API reference
SCIM provisioning
The SCIM 2.0 endpoints an identity provider calls, and the token that opens them.
Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.
| Operation | Method and path | Who may call it |
|---|---|---|
| Get provisioning status | GET /api/orgs/{org}/scim | admin |
| Turn off provisioning | DELETE /api/orgs/{org}/scim | console only (owner) |
| Issue a provisioning token | POST /api/orgs/{org}/scim/token | console only (owner) |
| Get SCIM capabilities | GET /api/scim/v2/ServiceProviderConfig | SCIM token |
| List SCIM resource types | GET /api/scim/v2/ResourceTypes | SCIM token |
| List SCIM schemas | GET /api/scim/v2/Schemas | SCIM token |
| List provisioned users | GET /api/scim/v2/Users | SCIM token |
| Provision a user | POST /api/scim/v2/Users | SCIM token |
| Get a provisioned user | GET /api/scim/v2/Users/{id} | SCIM token |
| Replace a provisioned user | PUT /api/scim/v2/Users/{id} | SCIM token |
| Update a provisioned user | PATCH /api/scim/v2/Users/{id} | SCIM token |
| Deprovision a user | DELETE /api/scim/v2/Users/{id} | SCIM token |
| List SCIM groups | GET /api/scim/v2/Groups | SCIM token |
| Create a SCIM group | POST /api/scim/v2/Groups | SCIM token |
#Get provisioning status
GET /api/orgs/{org}/scim
Says whether SCIM provisioning is on, the base address to give the identity provider, when the token was issued and last used, and how many users the identity provider manages.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/scim"
Answer (200, application/json)
A ScimStatus object.
{
"enabled": true,
"baseUrl": "https://app.nullgap.dev/api/scim/v2",
"tokenCreatedAt": "2026-11-01T12:00:00.000Z",
"tokenLastUsedAt": "2026-11-16T09:00:00.000Z",
"tokenExpiresAt": "2027-11-01T12:00:00.000Z",
"lockedUntil": "2026-11-16T09:15:00.000Z",
"users": 24,
"activeUsers": 22
}
#Turn off provisioning
DELETE /api/orgs/{org}/scim
Deletes the provisioning token, so the identity provider can no longer make changes. People who were provisioned keep their memberships, and the provisioned user records are kept for when provisioning is turned on again. Succeeds even when provisioning was already off.
Who may call it: A signed-in owner in the console. No API key may call it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Answer (200, application/json)
An empty object.
{}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 403 | step_up_required | Your account has a second factor and this session has not passed a second-factor check in the last 15 minutes. Confirm with a code or a passkey, then call again. |
#Issue a provisioning token
POST /api/orgs/{org}/scim/token
Turns SCIM provisioning on and returns its bearer token. If a token already exists it is replaced and stops working at once. The token is shown only in this answer. Single sign-on must already have at least one allowed email domain, because provisioning only accepts addresses on those domains. Takes no request body.
Who may call it: A signed-in owner in the console. No API key may call it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Answer (200, application/json)
A ScimToken object.
{
"token": "ngscim_EXAMPLEtokenEXAMPLEtokenEXAMPLEtokenEXAMPLE0",
"status": {
"enabled": true,
"baseUrl": "https://app.nullgap.dev/api/scim/v2",
"tokenCreatedAt": "2026-11-01T12:00:00.000Z",
"tokenLastUsedAt": "2026-11-16T09:00:00.000Z",
"tokenExpiresAt": "2027-11-01T12:00:00.000Z",
"lockedUntil": "2026-11-16T09:15:00.000Z",
"users": 24,
"activeUsers": 22
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 403 | step_up_required | Your account has a second factor and this session has not passed a second-factor check in the last 15 minutes. Confirm with a code or a passkey, then call again. |
| 400 | sso_first | The organisation has no single sign-on configuration with at least one allowed email domain. |
#Get SCIM capabilities
GET /api/scim/v2/ServiceProviderConfig
Says what this SCIM server supports: PATCH and simple filters, and no bulk operations, sorting, entity tags or password changes. Authenticate with Authorization: Bearer <token>, using the organisation's SCIM token (it begins ngscim_); the token decides which organisation the call acts on. Answers are application/scim+json, and failures use the SCIM error format (schemas, status, detail and sometimes scimType) instead of the usual error object.
Who may call it: The organisation’s SCIM token as a bearer token, not an API key.
Example request
curl -s -H "Authorization: Bearer $NULLGAP_SCIM_TOKEN" \
"$NULLGAP_URL/api/scim/v2/ServiceProviderConfig"
Answer (200, application/scim+json)
A ScimServiceProviderConfig object.
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
],
"patch": {
"supported": true
},
"bulk": {
"supported": false,
"maxOperations": 0,
"maxPayloadSize": 0
},
"filter": {
"supported": true,
"maxResults": 200
},
"changePassword": {
"supported": false
},
"sort": {
"supported": false
},
"etag": {
"supported": false
},
"authenticationSchemes": [
{
"type": "oauthbearertoken",
"name": "Bearer token",
"description": "The token issued in Nullgap under Settings → Access → SCIM provisioning.",
"primary": true
}
],
"meta": {
"resourceType": "ServiceProviderConfig",
"location": "https://app.nullgap.dev/api/scim/v2/ServiceProviderConfig"
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 401 | 401 | The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format. |
#List SCIM resource types
GET /api/scim/v2/ResourceTypes
Lists the kinds of resource this SCIM server has. There is one: User. Authenticate with Authorization: Bearer <token>, using the organisation's SCIM token (it begins ngscim_); the token decides which organisation the call acts on. Answers are application/scim+json, and failures use the SCIM error format (schemas, status, detail and sometimes scimType) instead of the usual error object.
Who may call it: The organisation’s SCIM token as a bearer token, not an API key.
Example request
curl -s -H "Authorization: Bearer $NULLGAP_SCIM_TOKEN" \
"$NULLGAP_URL/api/scim/v2/ResourceTypes"
Answer (200, application/scim+json)
A ScimResourceTypeList object.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 1,
"startIndex": 1,
"itemsPerPage": 1,
"Resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:ResourceType"
],
"id": "User",
"name": "User",
"endpoint": "/Users",
"schema": "urn:ietf:params:scim:schemas:core:2.0:User",
"meta": {
"resourceType": "ResourceType",
"location": "https://app.nullgap.dev/api/scim/v2/ResourceTypes/User"
}
}
]
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 401 | 401 | The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format. |
#List SCIM schemas
GET /api/scim/v2/Schemas
Lists the SCIM schemas this server has. There is one, for User, with the attributes Nullgap keeps. Authenticate with Authorization: Bearer <token>, using the organisation's SCIM token (it begins ngscim_); the token decides which organisation the call acts on. Answers are application/scim+json, and failures use the SCIM error format (schemas, status, detail and sometimes scimType) instead of the usual error object.
Who may call it: The organisation’s SCIM token as a bearer token, not an API key.
Example request
curl -s -H "Authorization: Bearer $NULLGAP_SCIM_TOKEN" \
"$NULLGAP_URL/api/scim/v2/Schemas"
Answer (200, application/scim+json)
A ScimSchemaList object.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 1,
"startIndex": 1,
"itemsPerPage": 1,
"Resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Schema"
],
"id": "urn:ietf:params:scim:schemas:core:2.0:User",
"name": "User",
"attributes": [
{
"name": "userName",
"type": "string",
"multiValued": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "server",
"subAttributes": [
{
"name": "userName",
"type": "string",
"multiValued": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "server"
}
]
}
],
"meta": {
"resourceType": "Schema",
"location": "https://app.nullgap.dev/api/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
}
}
]
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 401 | 401 | The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format. |
#List provisioned users
GET /api/scim/v2/Users
Lists the users the identity provider manages in the organisation, oldest first, in a SCIM ListResponse. It does not list members who joined another way. Paging uses SCIM's startIndex and count, not limit and offset. Authenticate with Authorization: Bearer <token>, using the organisation's SCIM token (it begins ngscim_); the token decides which organisation the call acts on. Answers are application/scim+json, and failures use the SCIM error format (schemas, status, detail and sometimes scimType) instead of the usual error object.
Who may call it: The organisation’s SCIM token as a bearer token, not an API key.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
filter | string | no | One equality filter, in the form <attribute> eq "<value>". The attribute is userName, externalId, id, emails.value or emails[type eq "work"].value. userName and the email forms match without regard to case, and the email forms match against userName. Any other filter is refused. |
startIndex | integer | no | The position of the first user to return, counting from 1. Default 1. |
count | integer | no | How many users to return, 0 to 200. Default 200. 0 returns the total with no users. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_SCIM_TOKEN" \
"$NULLGAP_URL/api/scim/v2/Users"
Answer (200, application/scim+json)
A ScimUserList object.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 24,
"startIndex": 1,
"itemsPerPage": 1,
"Resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "scu_7e2a91c4b05d",
"externalId": "00u1a2b3c4d5e6f7g8h9",
"userName": "dana@acme.example",
"name": {
"givenName": "Dana",
"familyName": "Okafor",
"formatted": "Dana Okafor"
},
"displayName": "Dana Okafor",
"emails": [
{
"value": "dana@acme.example",
"type": "work",
"primary": true
}
],
"active": true,
"meta": {
"resourceType": "User",
"created": "2026-11-02T10:00:00.000Z",
"lastModified": "2026-11-12T16:40:00.000Z",
"location": "https://app.nullgap.dev/api/scim/v2/Users/scu_7e2a91c4b05d"
}
}
]
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 401 | 401 | The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format. |
| 400 | invalidFilter | The filter is not a single eq comparison, or names an attribute that cannot be filtered on. |
#Provision a user
POST /api/scim/v2/Users
Creates a SCIM user and, when it is active, gives the person a membership of the organisation with the single sign-on default role. A Nullgap account is created for the email address if there is none. The address must be on one of the organisation's allowed email domains, and for an active user the domain must be verified. Answers 201 with the user and a Location header. Authenticate with Authorization: Bearer <token>, using the organisation's SCIM token (it begins ngscim_); the token decides which organisation the call acts on. Answers are application/scim+json, and failures use the SCIM error format (schemas, status, detail and sometimes scimType) instead of the usual error object.
Who may call it: The organisation’s SCIM token as a bearer token, not an API key.
Request body (application/scim+json)
| Field | Type | Required | Description |
|---|---|---|---|
schemas | array of string | no | The SCIM schemas of the message. Accepted and not checked. |
userName | string | yes | The sign-in name, normally the person's work email address. Unique within the organisation, compared without regard to case. Trimmed, and cut to 300 characters. If it is not an email address, emails must supply one. |
externalId | string | no | The identity provider's own id for the person. Trimmed, and cut to 300 characters. |
name | object | no | The person's name. formatted and other parts are ignored. |
name.givenName | string | no | First name. Trimmed, and cut to 200 characters. |
name.familyName | string | no | Last name. Trimmed, and cut to 200 characters. |
displayName | string | no | The name to show. Trimmed, and cut to 200 characters. Used as the name of a newly created Nullgap account. |
emails | array of object | no | Email addresses. Read only when userName is not an email address: the primary one is used, otherwise the one of type work, otherwise the first. They are not stored. |
emails[].value | string | yes | An email address. |
emails[].type | string | no | The kind of address, for example work. |
emails[].primary | boolean or string | no | True for the main address. The text "true" or "false" is accepted too. |
active | boolean or string | no | True gives the person a membership of the organisation; false takes it away and ends their single sign-on sessions for it. The text "true" or "false" is accepted too. Any other value is refused. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_SCIM_TOKEN" \
-H "Content-Type: application/scim+json" \
-d '{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"userName":"dana@acme.example","externalId":"00u1a2b3c4d5e6f7g8h9","name":{"givenName":"Dana","familyName":"Okafor"},"displayName":"Dana Okafor","emails":[{"value":"dana@acme.example","type":"work","primary":true}],"active":true}' \
"$NULLGAP_URL/api/scim/v2/Users"
Answer (201, application/scim+json)
A ScimUser object.
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "scu_7e2a91c4b05d",
"externalId": "00u1a2b3c4d5e6f7g8h9",
"userName": "dana@acme.example",
"name": {
"givenName": "Dana",
"familyName": "Okafor",
"formatted": "Dana Okafor"
},
"displayName": "Dana Okafor",
"emails": [
{
"value": "dana@acme.example",
"type": "work",
"primary": true
}
],
"active": true,
"meta": {
"resourceType": "User",
"created": "2026-11-02T10:00:00.000Z",
"lastModified": "2026-11-12T16:40:00.000Z",
"location": "https://app.nullgap.dev/api/scim/v2/Users/scu_7e2a91c4b05d"
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 401 | 401 | The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format. |
| 400 | invalidValue | userName is missing or blank. Neither userName nor a usable entry in emails is an email address, active is not true or false, the email domain is not on the organisation's allowed list, or the user is active and the domain has not been verified. |
| 409 | uniqueness | Another SCIM user in the organisation already has that userName (compared without regard to case). |
| 400 | 400 | The organisation has no single sign-on configuration with allowed email domains, so nobody can be provisioned. This failure carries no scimType. |
| 400 | mutability | The change would take away the membership of an organisation owner. Change their role in Nullgap first. |
#Get a provisioned user
GET /api/scim/v2/Users/{id}
Authenticate with Authorization: Bearer <token>, using the organisation's SCIM token (it begins ngscim_); the token decides which organisation the call acts on. Answers are application/scim+json, and failures use the SCIM error format (schemas, status, detail and sometimes scimType) instead of the usual error object.
Who may call it: The organisation’s SCIM token as a bearer token, not an API key.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | The SCIM user id Nullgap issued, for example scu_7e2a91c4b05d. It is not the identity provider's externalId. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_SCIM_TOKEN" \
"$NULLGAP_URL/api/scim/v2/Users/scu_7e2a91c4b05d"
Answer (200, application/scim+json)
A ScimUser object.
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "scu_7e2a91c4b05d",
"externalId": "00u1a2b3c4d5e6f7g8h9",
"userName": "dana@acme.example",
"name": {
"givenName": "Dana",
"familyName": "Okafor",
"formatted": "Dana Okafor"
},
"displayName": "Dana Okafor",
"emails": [
{
"value": "dana@acme.example",
"type": "work",
"primary": true
}
],
"active": true,
"meta": {
"resourceType": "User",
"created": "2026-11-02T10:00:00.000Z",
"lastModified": "2026-11-12T16:40:00.000Z",
"location": "https://app.nullgap.dev/api/scim/v2/Users/scu_7e2a91c4b05d"
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 401 | 401 | The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format. |
| 404 | 404 | No SCIM user with that id exists in the organisation. |
#Replace a provisioned user
PUT /api/scim/v2/Users/{id}
Replaces the user's attributes. Attributes left out are cleared, and active becomes true when left out; only userName is kept when left out. Setting active to false removes the person's membership and ends their single sign-on sessions for the organisation; setting it back to true restores the membership with the role they had. Changing the email address moves the membership to the account with the new address. Authenticate with Authorization: Bearer <token>, using the organisation's SCIM token (it begins ngscim_); the token decides which organisation the call acts on. Answers are application/scim+json, and failures use the SCIM error format (schemas, status, detail and sometimes scimType) instead of the usual error object.
Who may call it: The organisation’s SCIM token as a bearer token, not an API key.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | The SCIM user id Nullgap issued, for example scu_7e2a91c4b05d. It is not the identity provider's externalId. |
Request body (application/scim+json)
| Field | Type | Required | Description |
|---|---|---|---|
schemas | array of string | no | The SCIM schemas of the message. Accepted and not checked. |
userName | string | no | The sign-in name, normally the person's work email address. Unique within the organisation, compared without regard to case. Trimmed, and cut to 300 characters. If it is not an email address, emails must supply one. |
externalId | string | no | The identity provider's own id for the person. Trimmed, and cut to 300 characters. |
name | object | no | The person's name. formatted and other parts are ignored. |
name.givenName | string | no | First name. Trimmed, and cut to 200 characters. |
name.familyName | string | no | Last name. Trimmed, and cut to 200 characters. |
displayName | string | no | The name to show. Trimmed, and cut to 200 characters. Used as the name of a newly created Nullgap account. |
emails | array of object | no | Email addresses. Read only when userName is not an email address: the primary one is used, otherwise the one of type work, otherwise the first. They are not stored. |
emails[].value | string | yes | An email address. |
emails[].type | string | no | The kind of address, for example work. |
emails[].primary | boolean or string | no | True for the main address. The text "true" or "false" is accepted too. |
active | boolean or string | no | True gives the person a membership of the organisation; false takes it away and ends their single sign-on sessions for it. The text "true" or "false" is accepted too. Any other value is refused. |
Example request
curl -s -X PUT -H "Authorization: Bearer $NULLGAP_SCIM_TOKEN" \
-H "Content-Type: application/scim+json" \
-d '{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"userName":"dana@acme.example","externalId":"00u1a2b3c4d5e6f7g8h9","name":{"givenName":"Dana","familyName":"Okafor"},"displayName":"Dana Okafor","emails":[{"value":"dana@acme.example","type":"work","primary":true}],"active":true}' \
"$NULLGAP_URL/api/scim/v2/Users/scu_7e2a91c4b05d"
Answer (200, application/scim+json)
A ScimUser object.
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "scu_7e2a91c4b05d",
"externalId": "00u1a2b3c4d5e6f7g8h9",
"userName": "dana@acme.example",
"name": {
"givenName": "Dana",
"familyName": "Okafor",
"formatted": "Dana Okafor"
},
"displayName": "Dana Okafor",
"emails": [
{
"value": "dana@acme.example",
"type": "work",
"primary": true
}
],
"active": true,
"meta": {
"resourceType": "User",
"created": "2026-11-02T10:00:00.000Z",
"lastModified": "2026-11-12T16:40:00.000Z",
"location": "https://app.nullgap.dev/api/scim/v2/Users/scu_7e2a91c4b05d"
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 401 | 401 | The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format. |
| 404 | 404 | No SCIM user with that id exists in the organisation. |
| 400 | invalidValue | userName is blank. Neither userName nor a usable entry in emails is an email address, active is not true or false, the email domain is not on the organisation's allowed list, or the user is active and the domain has not been verified. |
| 409 | uniqueness | Another SCIM user in the organisation already has that userName (compared without regard to case). |
| 400 | 400 | The organisation has no single sign-on configuration with allowed email domains, so nobody can be provisioned. This failure carries no scimType. |
| 400 | mutability | The change would take away the membership of an organisation owner. Change their role in Nullgap first. |
#Update a provisioned user
PATCH /api/scim/v2/Users/{id}
Applies a SCIM PatchOp. The operations add, replace and remove are supported on active, userName, displayName, externalId, name.givenName, name.familyName, name and emails; changes to any other attribute are accepted and ignored. All operations in one request are applied together. Setting active to false removes the person's membership and ends their single sign-on sessions for the organisation; setting it back to true restores the membership with the role they had. Authenticate with Authorization: Bearer <token>, using the organisation's SCIM token (it begins ngscim_); the token decides which organisation the call acts on. Answers are application/scim+json, and failures use the SCIM error format (schemas, status, detail and sometimes scimType) instead of the usual error object.
Who may call it: The organisation’s SCIM token as a bearer token, not an API key.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | The SCIM user id Nullgap issued, for example scu_7e2a91c4b05d. It is not the identity provider's externalId. |
Request body (application/scim+json)
| Field | Type | Required | Description |
|---|---|---|---|
schemas | array of string | yes | Must include urn:ietf:params:scim:api:messages:2.0:PatchOp. |
Operations | array of object | yes | The changes, applied together as one update. |
Operations[].op | string | yes | What to do. Upper and lower case are both accepted. add and replace behave the same. remove blanks name.givenName, name.familyName, displayName or externalId, and is ignored for any other path. |
Operations[].path | string | no | The attribute to change, in any letter case: active, userName, displayName, externalId, name.givenName, name.familyName, name, emails, emails.value or emails[type eq "work"].value. Any other path is accepted and ignored. Leave it out to send several attributes at once in value. |
Operations[].value | any | no | The new value. With a path, the value of that attribute. Without one, an object whose keys are the paths above, for example { "active": false }. Not used by remove. |
Example request
curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_SCIM_TOKEN" \
-H "Content-Type: application/scim+json" \
-d '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations":[{"op":"replace","path":"active","value":false}]}' \
"$NULLGAP_URL/api/scim/v2/Users/scu_7e2a91c4b05d"
Answer (200, application/scim+json)
A ScimUser object.
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "scu_7e2a91c4b05d",
"externalId": "00u1a2b3c4d5e6f7g8h9",
"userName": "dana@acme.example",
"name": {
"givenName": "Dana",
"familyName": "Okafor",
"formatted": "Dana Okafor"
},
"displayName": "Dana Okafor",
"emails": [
{
"value": "dana@acme.example",
"type": "work",
"primary": true
}
],
"active": true,
"meta": {
"resourceType": "User",
"created": "2026-11-02T10:00:00.000Z",
"lastModified": "2026-11-12T16:40:00.000Z",
"location": "https://app.nullgap.dev/api/scim/v2/Users/scu_7e2a91c4b05d"
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 401 | 401 | The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format. |
| 404 | 404 | No SCIM user with that id exists in the organisation. |
| 400 | invalidSyntax | The body is not a PatchOp message with an Operations array, an operation is not add, replace or remove, or an operation has neither a path nor an object value. |
| 400 | invalidValue | userName is set to a blank value. Neither userName nor a usable entry in emails is an email address, active is not true or false, the email domain is not on the organisation's allowed list, or the user is active and the domain has not been verified. |
| 409 | uniqueness | Another SCIM user in the organisation already has that userName (compared without regard to case). |
| 400 | 400 | The organisation has no single sign-on configuration with allowed email domains, so nobody can be provisioned. This failure carries no scimType. |
| 400 | mutability | The change would take away the membership of an organisation owner. Change their role in Nullgap first. |
#Deprovision a user
DELETE /api/scim/v2/Users/{id}
Deletes the SCIM user. If it was active, the person's membership of the organisation is removed and their single sign-on sessions for it are ended. The person's Nullgap account itself is not deleted. Answers 204 with no body. Authenticate with Authorization: Bearer <token>, using the organisation's SCIM token (it begins ngscim_); the token decides which organisation the call acts on. Answers are application/scim+json, and failures use the SCIM error format (schemas, status, detail and sometimes scimType) instead of the usual error object.
Who may call it: The organisation’s SCIM token as a bearer token, not an API key.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | The SCIM user id Nullgap issued, for example scu_7e2a91c4b05d. It is not the identity provider's externalId. |
Example request
curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_SCIM_TOKEN" \
"$NULLGAP_URL/api/scim/v2/Users/scu_7e2a91c4b05d"
Answer (204)
No body.
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 401 | 401 | The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format. |
| 404 | 404 | No SCIM user with that id exists in the organisation. |
| 400 | mutability | The change would take away the membership of an organisation owner. Change their role in Nullgap first. |
#List SCIM groups
GET /api/scim/v2/Groups
Always answers an empty SCIM ListResponse. Groups are not provisioned; the route exists so identity providers that ask for groups get a well-formed answer. Authenticate with Authorization: Bearer <token>, using the organisation's SCIM token (it begins ngscim_); the token decides which organisation the call acts on. Answers are application/scim+json, and failures use the SCIM error format (schemas, status, detail and sometimes scimType) instead of the usual error object.
Who may call it: The organisation’s SCIM token as a bearer token, not an API key.
Example request
curl -s -H "Authorization: Bearer $NULLGAP_SCIM_TOKEN" \
"$NULLGAP_URL/api/scim/v2/Groups"
Answer (200, application/scim+json)
A ScimEmptyList object.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 0,
"startIndex": 1,
"itemsPerPage": 0,
"Resources": [
{}
]
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 401 | 401 | The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format. |
#Create a SCIM group
POST /api/scim/v2/Groups
Not supported: this call always answers 501 with a SCIM error. Assign people to the application individually, or by group at the identity provider; Nullgap receives users only. The request body is ignored. Authenticate with Authorization: Bearer <token>, using the organisation's SCIM token (it begins ngscim_); the token decides which organisation the call acts on. Answers are application/scim+json, and failures use the SCIM error format (schemas, status, detail and sometimes scimType) instead of the usual error object.
Who may call it: The organisation’s SCIM token as a bearer token, not an API key.
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_SCIM_TOKEN" \
"$NULLGAP_URL/api/scim/v2/Groups"
Answer (401, application/json)
A Error object.
{
"error": {
"code": "not_found",
"message": "Finding not found",
"requestId": "req_Zk3vQp81LmNx"
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 401 | 401 | The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format. |
| 501 | 501 | Always. Group provisioning is not supported. |
#Objects
The objects the operations above take and return.
#ScimStatus
The state of SCIM provisioning for an organisation. Users only: groups are not provisioned.
| Field | Type | Always present | Description |
|---|---|---|---|
enabled | boolean | yes | True when a provisioning token exists. |
baseUrl | string | yes | The SCIM base address to give the identity provider. |
tokenCreatedAt | string or null | yes | When the current token was issued. Null when provisioning is off. |
tokenLastUsedAt | string or null | yes | When the token was last used, to the nearest minute. Null if never, or when provisioning is off. |
tokenExpiresAt | string or null | yes | When the token stops working, chosen when it was issued. Null when it does not expire, or when provisioning is off. |
lockedUntil | string or null | yes | Set while provisioning is paused after repeated failed attempts to authenticate: every SCIM request is refused until then. Null when it is not paused. |
users | integer | yes | How many users the identity provider manages in this organisation. |
activeUsers | integer | yes | How many of them are active. |
#ScimToken
| Field | Type | Always present | Description |
|---|---|---|---|
token | string | yes | The bearer token for the identity provider. It begins ngscim_. It is shown only in this answer: only its hash is kept. |
status | ScimStatus | yes |
#ScimServiceProviderConfig
What this SCIM server supports.
| Field | Type | Always present | Description |
|---|---|---|---|
schemas | array of string | yes | The SCIM schemas this message follows. Always this one value. |
patch | object | yes | |
patch.supported | boolean | yes | PATCH is supported. |
bulk | object | yes | |
bulk.supported | boolean | yes | Bulk operations are not supported. |
bulk.maxOperations | integer | yes | Always 0. |
bulk.maxPayloadSize | integer | yes | Always 0. |
filter | object | yes | |
filter.supported | boolean | yes | Simple equality filters are supported on the user list. |
filter.maxResults | integer | yes | The most users one list answer returns. Always 200. |
changePassword | object | yes | |
changePassword.supported | boolean | yes | Nullgap holds no passwords. |
sort | object | yes | |
sort.supported | boolean | yes | Sorting is not supported. Lists are oldest first. |
etag | object | yes | |
etag.supported | boolean | yes | Entity tags are not supported. |
authenticationSchemes | array of object | yes | How to authenticate. Always one entry. |
authenticationSchemes[].type | string | yes | Always oauthbearertoken. |
authenticationSchemes[].name | string | yes | The name of the scheme. |
authenticationSchemes[].description | string | yes | Where the token comes from. |
authenticationSchemes[].primary | boolean | yes | Always true: it is the only scheme. |
meta | object | yes | SCIM bookkeeping for the resource. |
meta.resourceType | string | yes | The kind of SCIM resource. |
meta.location | string | yes | The full URL of this resource. |
#ScimResourceTypeList
The resource types this SCIM server has. Users only.
| Field | Type | Always present | Description |
|---|---|---|---|
schemas | array of string | yes | The SCIM schemas this message follows. Always this one value. |
totalResults | integer | yes | How many resources match in all. |
startIndex | integer | yes | The position of the first resource returned, counting from 1. |
itemsPerPage | integer | yes | How many resources are in this answer. |
Resources | array of object | yes | Always one entry: the User resource type. |
Resources[].schemas | array of string | yes | The SCIM schemas this message follows. Always this one value. |
Resources[].id | string | yes | Always User. |
Resources[].name | string | yes | Always User. |
Resources[].endpoint | string | yes | The path of the resource under the SCIM base address. |
Resources[].schema | string | yes | The schema of the resource. |
Resources[].meta | object | yes | SCIM bookkeeping for the resource. |
Resources[].meta.resourceType | string | yes | The kind of SCIM resource. |
Resources[].meta.location | string | yes | The full URL of this resource. |
#ScimSchemaList
The schemas this SCIM server has. Users only.
| Field | Type | Always present | Description |
|---|---|---|---|
schemas | array of string | yes | The SCIM schemas this message follows. Always this one value. |
totalResults | integer | yes | How many resources match in all. |
startIndex | integer | yes | The position of the first resource returned, counting from 1. |
itemsPerPage | integer | yes | How many resources are in this answer. |
Resources | array of object | yes | Always one entry: the User schema. |
Resources[].schemas | array of string | yes | The SCIM schemas this message follows. Always this one value. |
Resources[].id | string | yes | The schema name. |
Resources[].name | string | yes | Always User. |
Resources[].attributes | array of object | yes | The attributes Nullgap keeps: userName, externalId, displayName, name, emails and active. |
Resources[].attributes[].name | string | yes | The attribute name. |
Resources[].attributes[].type | string | yes | The kind of value. One of: string, boolean, complex. |
Resources[].attributes[].multiValued | boolean | yes | True when the attribute holds a list. |
Resources[].attributes[].required | boolean | yes | True when a user cannot be created without it. Only userName is required. |
Resources[].attributes[].caseExact | boolean | yes | Always false: values are compared without regard to case. |
Resources[].attributes[].mutability | string | yes | Whether a client may set it. Only name.formatted is read-only. |
Resources[].attributes[].returned | string | yes | Always default: the attribute is returned in every answer. |
Resources[].attributes[].uniqueness | string | yes | Whether two users may share a value. Only userName must be unique. |
Resources[].attributes[].subAttributes | array of object | no | The parts of a complex attribute (name and emails). Absent on simple attributes. |
Resources[].attributes[].subAttributes[].name | string | yes | The attribute name. |
Resources[].attributes[].subAttributes[].type | string | yes | The kind of value. One of: string, boolean, complex. |
Resources[].attributes[].subAttributes[].multiValued | boolean | yes | True when the attribute holds a list. |
Resources[].attributes[].subAttributes[].required | boolean | yes | True when a user cannot be created without it. Only userName is required. |
Resources[].attributes[].subAttributes[].caseExact | boolean | yes | Always false: values are compared without regard to case. |
Resources[].attributes[].subAttributes[].mutability | string | yes | Whether a client may set it. Only name.formatted is read-only. |
Resources[].attributes[].subAttributes[].returned | string | yes | Always default: the attribute is returned in every answer. |
Resources[].attributes[].subAttributes[].uniqueness | string | yes | Whether two users may share a value. Only userName must be unique. |
Resources[].meta | object | yes | SCIM bookkeeping for the resource. |
Resources[].meta.resourceType | string | yes | The kind of SCIM resource. |
Resources[].meta.location | string | yes | The full URL of this resource. |
#ScimUserList
A SCIM ListResponse of users.
| Field | Type | Always present | Description |
|---|---|---|---|
schemas | array of string | yes | The SCIM schemas this message follows. Always this one value. |
totalResults | integer | yes | How many resources match in all. |
startIndex | integer | yes | The position of the first resource returned, counting from 1. |
itemsPerPage | integer | yes | How many resources are in this answer. |
Resources | array of ScimUser | yes | The users on this page, oldest first. |
#ScimUserCreate
A SCIM user to create. Attributes not listed here (title, addresses, the enterprise extension and so on) are accepted and not kept.
| Field | Type | Always present | Description |
|---|---|---|---|
schemas | array of string | no | The SCIM schemas of the message. Accepted and not checked. |
userName | string | yes | The sign-in name, normally the person's work email address. Unique within the organisation, compared without regard to case. Trimmed, and cut to 300 characters. If it is not an email address, emails must supply one. |
externalId | string | no | The identity provider's own id for the person. Trimmed, and cut to 300 characters. |
name | object | no | The person's name. formatted and other parts are ignored. |
name.givenName | string | no | First name. Trimmed, and cut to 200 characters. |
name.familyName | string | no | Last name. Trimmed, and cut to 200 characters. |
displayName | string | no | The name to show. Trimmed, and cut to 200 characters. Used as the name of a newly created Nullgap account. |
emails | array of object | no | Email addresses. Read only when userName is not an email address: the primary one is used, otherwise the one of type work, otherwise the first. They are not stored. |
emails[].value | string | yes | An email address. |
emails[].type | string | no | The kind of address, for example work. |
emails[].primary | boolean or string | no | True for the main address. The text "true" or "false" is accepted too. |
active | boolean or string | no | True gives the person a membership of the organisation; false takes it away and ends their single sign-on sessions for it. The text "true" or "false" is accepted too. Any other value is refused. |
#ScimUser
A SCIM user as Nullgap returns it. There are no groups, roles or enterprise attributes.
| Field | Type | Always present | Description |
|---|---|---|---|
schemas | array of string | yes | The SCIM schemas this message follows. Always this one value. |
id | string | yes | Nullgap's id for the SCIM user. |
externalId | string | no | The identity provider's own id for the person. Left out when none was sent. |
userName | string | yes | The sign-in name, as the identity provider sent it. |
name | object | yes | The person's name. |
name.givenName | string | yes | First name. Empty when not sent. |
name.familyName | string | yes | Last name. Empty when not sent. |
name.formatted | string | yes | First and last name joined by a space. Worked out by Nullgap; it cannot be set. |
displayName | string | yes | The name to show. Empty when not sent. |
emails | array of object | yes | Always exactly one entry, which repeats userName. Addresses sent in emails are not stored. |
emails[].value | string | yes | The same text as userName. |
emails[].type | string | yes | Always work. |
emails[].primary | boolean | yes | Always true. |
active | boolean | yes | True when the person has a membership of the organisation through provisioning. |
meta | object | yes | SCIM bookkeeping for the resource. |
meta.resourceType | string | yes | The kind of SCIM resource. |
meta.created | string | yes | When the SCIM user was created. |
meta.lastModified | string | yes | When it was last changed. |
meta.location | string | yes | The full URL of this resource. |
#ScimUserReplace
The whole SCIM user. externalId, the name parts and displayName are cleared when left out, and active becomes true when left out. Only userName keeps its stored value when left out.
| Field | Type | Always present | Description |
|---|---|---|---|
schemas | array of string | no | The SCIM schemas of the message. Accepted and not checked. |
userName | string | no | The sign-in name, normally the person's work email address. Unique within the organisation, compared without regard to case. Trimmed, and cut to 300 characters. If it is not an email address, emails must supply one. |
externalId | string | no | The identity provider's own id for the person. Trimmed, and cut to 300 characters. |
name | object | no | The person's name. formatted and other parts are ignored. |
name.givenName | string | no | First name. Trimmed, and cut to 200 characters. |
name.familyName | string | no | Last name. Trimmed, and cut to 200 characters. |
displayName | string | no | The name to show. Trimmed, and cut to 200 characters. Used as the name of a newly created Nullgap account. |
emails | array of object | no | Email addresses. Read only when userName is not an email address: the primary one is used, otherwise the one of type work, otherwise the first. They are not stored. |
emails[].value | string | yes | An email address. |
emails[].type | string | no | The kind of address, for example work. |
emails[].primary | boolean or string | no | True for the main address. The text "true" or "false" is accepted too. |
active | boolean or string | no | True gives the person a membership of the organisation; false takes it away and ends their single sign-on sessions for it. The text "true" or "false" is accepted too. Any other value is refused. |
#ScimPatch
A SCIM PatchOp message.
| Field | Type | Always present | Description |
|---|---|---|---|
schemas | array of string | yes | Must include urn:ietf:params:scim:api:messages:2.0:PatchOp. |
Operations | array of object | yes | The changes, applied together as one update. |
Operations[].op | string | yes | What to do. Upper and lower case are both accepted. add and replace behave the same. remove blanks name.givenName, name.familyName, displayName or externalId, and is ignored for any other path. |
Operations[].path | string | no | The attribute to change, in any letter case: active, userName, displayName, externalId, name.givenName, name.familyName, name, emails, emails.value or emails[type eq "work"].value. Any other path is accepted and ignored. Leave it out to send several attributes at once in value. |
Operations[].value | any | no | The new value. With a path, the value of that attribute. Without one, an object whose keys are the paths above, for example { "active": false }. Not used by remove. |
#ScimEmptyList
A SCIM ListResponse with nothing in it.
| Field | Type | Always present | Description |
|---|---|---|---|
schemas | array of string | yes | The SCIM schemas this message follows. Always this one value. |
totalResults | integer | yes | How many resources match in all. |
startIndex | integer | yes | The position of the first resource returned, counting from 1. |
itemsPerPage | integer | yes | How many resources are in this answer. |
Resources | array of object | yes | Always empty. |
#Error
Every failure has this shape, with a matching HTTP status.
| Field | Type | Always present | Description |
|---|---|---|---|
error | object | yes | |
error.code | string | yes | A short, stable name for the failure. Branch on this, not on the message. |
error.message | string | yes | One sentence for a person. |
error.requestId | string | yes | The id of this request, also sent as the X-Request-Id header. Quote it when you ask for help. |
Nullgap documentation