Nullgap.dev Docs

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.

OperationMethod and pathWho may call it
Get provisioning statusGET /api/orgs/{org}/scimadmin
Turn off provisioningDELETE /api/orgs/{org}/scimconsole only (owner)
Issue a provisioning tokenPOST /api/orgs/{org}/scim/tokenconsole only (owner)
Get SCIM capabilitiesGET /api/scim/v2/ServiceProviderConfigSCIM token
List SCIM resource typesGET /api/scim/v2/ResourceTypesSCIM token
List SCIM schemasGET /api/scim/v2/SchemasSCIM token
List provisioned usersGET /api/scim/v2/UsersSCIM token
Provision a userPOST /api/scim/v2/UsersSCIM token
Get a provisioned userGET /api/scim/v2/Users/{id}SCIM token
Replace a provisioned userPUT /api/scim/v2/Users/{id}SCIM token
Update a provisioned userPATCH /api/scim/v2/Users/{id}SCIM token
Deprovision a userDELETE /api/scim/v2/Users/{id}SCIM token
List SCIM groupsGET /api/scim/v2/GroupsSCIM token
Create a SCIM groupPOST /api/scim/v2/GroupsSCIM 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

NameTypeRequiredDescription
orgstringyesThe 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Answer (200, application/json)

An empty object.

{}

Errors specific to this call

StatusCodeWhen
403step_up_requiredYour 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

NameTypeRequiredDescription
orgstringyesThe 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

StatusCodeWhen
403step_up_requiredYour 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.
400sso_firstThe 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

StatusCodeWhen
401401The 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

StatusCodeWhen
401401The 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

StatusCodeWhen
401401The 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

NameTypeRequiredDescription
filterstringnoOne 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.
startIndexintegernoThe position of the first user to return, counting from 1. Default 1.
countintegernoHow 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

StatusCodeWhen
401401The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format.
400invalidFilterThe 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)

FieldTypeRequiredDescription
schemasarray of stringnoThe SCIM schemas of the message. Accepted and not checked.
userNamestringyesThe 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.
externalIdstringnoThe identity provider's own id for the person. Trimmed, and cut to 300 characters.
nameobjectnoThe person's name. formatted and other parts are ignored.
name.givenNamestringnoFirst name. Trimmed, and cut to 200 characters.
name.familyNamestringnoLast name. Trimmed, and cut to 200 characters.
displayNamestringnoThe name to show. Trimmed, and cut to 200 characters. Used as the name of a newly created Nullgap account.
emailsarray of objectnoEmail 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[].valuestringyesAn email address.
emails[].typestringnoThe kind of address, for example work.
emails[].primaryboolean or stringnoTrue for the main address. The text "true" or "false" is accepted too.
activeboolean or stringnoTrue 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

StatusCodeWhen
401401The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format.
400invalidValueuserName 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.
409uniquenessAnother SCIM user in the organisation already has that userName (compared without regard to case).
400400The organisation has no single sign-on configuration with allowed email domains, so nobody can be provisioned. This failure carries no scimType.
400mutabilityThe 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

NameTypeRequiredDescription
idstringyesThe 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

StatusCodeWhen
401401The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format.
404404No 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

NameTypeRequiredDescription
idstringyesThe SCIM user id Nullgap issued, for example scu_7e2a91c4b05d. It is not the identity provider's externalId.

Request body (application/scim+json)

FieldTypeRequiredDescription
schemasarray of stringnoThe SCIM schemas of the message. Accepted and not checked.
userNamestringnoThe 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.
externalIdstringnoThe identity provider's own id for the person. Trimmed, and cut to 300 characters.
nameobjectnoThe person's name. formatted and other parts are ignored.
name.givenNamestringnoFirst name. Trimmed, and cut to 200 characters.
name.familyNamestringnoLast name. Trimmed, and cut to 200 characters.
displayNamestringnoThe name to show. Trimmed, and cut to 200 characters. Used as the name of a newly created Nullgap account.
emailsarray of objectnoEmail 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[].valuestringyesAn email address.
emails[].typestringnoThe kind of address, for example work.
emails[].primaryboolean or stringnoTrue for the main address. The text "true" or "false" is accepted too.
activeboolean or stringnoTrue 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

StatusCodeWhen
401401The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format.
404404No SCIM user with that id exists in the organisation.
400invalidValueuserName 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.
409uniquenessAnother SCIM user in the organisation already has that userName (compared without regard to case).
400400The organisation has no single sign-on configuration with allowed email domains, so nobody can be provisioned. This failure carries no scimType.
400mutabilityThe 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

NameTypeRequiredDescription
idstringyesThe SCIM user id Nullgap issued, for example scu_7e2a91c4b05d. It is not the identity provider's externalId.

Request body (application/scim+json)

FieldTypeRequiredDescription
schemasarray of stringyesMust include urn:ietf:params:scim:api:messages:2.0:PatchOp.
Operationsarray of objectyesThe changes, applied together as one update.
Operations[].opstringyesWhat 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[].pathstringnoThe 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[].valueanynoThe 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

StatusCodeWhen
401401The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format.
404404No SCIM user with that id exists in the organisation.
400invalidSyntaxThe 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.
400invalidValueuserName 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.
409uniquenessAnother SCIM user in the organisation already has that userName (compared without regard to case).
400400The organisation has no single sign-on configuration with allowed email domains, so nobody can be provisioned. This failure carries no scimType.
400mutabilityThe 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

NameTypeRequiredDescription
idstringyesThe 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

StatusCodeWhen
401401The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format.
404404No SCIM user with that id exists in the organisation.
400mutabilityThe 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

StatusCodeWhen
401401The 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

StatusCodeWhen
401401The bearer token is missing, is not a SCIM token, or was replaced or switched off. Answered in the SCIM error format.
501501Always. 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.

FieldTypeAlways presentDescription
enabledbooleanyesTrue when a provisioning token exists.
baseUrlstringyesThe SCIM base address to give the identity provider.
tokenCreatedAtstring or nullyesWhen the current token was issued. Null when provisioning is off.
tokenLastUsedAtstring or nullyesWhen the token was last used, to the nearest minute. Null if never, or when provisioning is off.
tokenExpiresAtstring or nullyesWhen the token stops working, chosen when it was issued. Null when it does not expire, or when provisioning is off.
lockedUntilstring or nullyesSet while provisioning is paused after repeated failed attempts to authenticate: every SCIM request is refused until then. Null when it is not paused.
usersintegeryesHow many users the identity provider manages in this organisation.
activeUsersintegeryesHow many of them are active.

#ScimToken

FieldTypeAlways presentDescription
tokenstringyesThe bearer token for the identity provider. It begins ngscim_. It is shown only in this answer: only its hash is kept.
statusScimStatusyes

#ScimServiceProviderConfig

What this SCIM server supports.

FieldTypeAlways presentDescription
schemasarray of stringyesThe SCIM schemas this message follows. Always this one value.
patchobjectyes
patch.supportedbooleanyesPATCH is supported.
bulkobjectyes
bulk.supportedbooleanyesBulk operations are not supported.
bulk.maxOperationsintegeryesAlways 0.
bulk.maxPayloadSizeintegeryesAlways 0.
filterobjectyes
filter.supportedbooleanyesSimple equality filters are supported on the user list.
filter.maxResultsintegeryesThe most users one list answer returns. Always 200.
changePasswordobjectyes
changePassword.supportedbooleanyesNullgap holds no passwords.
sortobjectyes
sort.supportedbooleanyesSorting is not supported. Lists are oldest first.
etagobjectyes
etag.supportedbooleanyesEntity tags are not supported.
authenticationSchemesarray of objectyesHow to authenticate. Always one entry.
authenticationSchemes[].typestringyesAlways oauthbearertoken.
authenticationSchemes[].namestringyesThe name of the scheme.
authenticationSchemes[].descriptionstringyesWhere the token comes from.
authenticationSchemes[].primarybooleanyesAlways true: it is the only scheme.
metaobjectyesSCIM bookkeeping for the resource.
meta.resourceTypestringyesThe kind of SCIM resource.
meta.locationstringyesThe full URL of this resource.

#ScimResourceTypeList

The resource types this SCIM server has. Users only.

FieldTypeAlways presentDescription
schemasarray of stringyesThe SCIM schemas this message follows. Always this one value.
totalResultsintegeryesHow many resources match in all.
startIndexintegeryesThe position of the first resource returned, counting from 1.
itemsPerPageintegeryesHow many resources are in this answer.
Resourcesarray of objectyesAlways one entry: the User resource type.
Resources[].schemasarray of stringyesThe SCIM schemas this message follows. Always this one value.
Resources[].idstringyesAlways User.
Resources[].namestringyesAlways User.
Resources[].endpointstringyesThe path of the resource under the SCIM base address.
Resources[].schemastringyesThe schema of the resource.
Resources[].metaobjectyesSCIM bookkeeping for the resource.
Resources[].meta.resourceTypestringyesThe kind of SCIM resource.
Resources[].meta.locationstringyesThe full URL of this resource.

#ScimSchemaList

The schemas this SCIM server has. Users only.

FieldTypeAlways presentDescription
schemasarray of stringyesThe SCIM schemas this message follows. Always this one value.
totalResultsintegeryesHow many resources match in all.
startIndexintegeryesThe position of the first resource returned, counting from 1.
itemsPerPageintegeryesHow many resources are in this answer.
Resourcesarray of objectyesAlways one entry: the User schema.
Resources[].schemasarray of stringyesThe SCIM schemas this message follows. Always this one value.
Resources[].idstringyesThe schema name.
Resources[].namestringyesAlways User.
Resources[].attributesarray of objectyesThe attributes Nullgap keeps: userName, externalId, displayName, name, emails and active.
Resources[].attributes[].namestringyesThe attribute name.
Resources[].attributes[].typestringyesThe kind of value. One of: string, boolean, complex.
Resources[].attributes[].multiValuedbooleanyesTrue when the attribute holds a list.
Resources[].attributes[].requiredbooleanyesTrue when a user cannot be created without it. Only userName is required.
Resources[].attributes[].caseExactbooleanyesAlways false: values are compared without regard to case.
Resources[].attributes[].mutabilitystringyesWhether a client may set it. Only name.formatted is read-only.
Resources[].attributes[].returnedstringyesAlways default: the attribute is returned in every answer.
Resources[].attributes[].uniquenessstringyesWhether two users may share a value. Only userName must be unique.
Resources[].attributes[].subAttributesarray of objectnoThe parts of a complex attribute (name and emails). Absent on simple attributes.
Resources[].attributes[].subAttributes[].namestringyesThe attribute name.
Resources[].attributes[].subAttributes[].typestringyesThe kind of value. One of: string, boolean, complex.
Resources[].attributes[].subAttributes[].multiValuedbooleanyesTrue when the attribute holds a list.
Resources[].attributes[].subAttributes[].requiredbooleanyesTrue when a user cannot be created without it. Only userName is required.
Resources[].attributes[].subAttributes[].caseExactbooleanyesAlways false: values are compared without regard to case.
Resources[].attributes[].subAttributes[].mutabilitystringyesWhether a client may set it. Only name.formatted is read-only.
Resources[].attributes[].subAttributes[].returnedstringyesAlways default: the attribute is returned in every answer.
Resources[].attributes[].subAttributes[].uniquenessstringyesWhether two users may share a value. Only userName must be unique.
Resources[].metaobjectyesSCIM bookkeeping for the resource.
Resources[].meta.resourceTypestringyesThe kind of SCIM resource.
Resources[].meta.locationstringyesThe full URL of this resource.

#ScimUserList

A SCIM ListResponse of users.

FieldTypeAlways presentDescription
schemasarray of stringyesThe SCIM schemas this message follows. Always this one value.
totalResultsintegeryesHow many resources match in all.
startIndexintegeryesThe position of the first resource returned, counting from 1.
itemsPerPageintegeryesHow many resources are in this answer.
Resourcesarray of ScimUseryesThe 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.

FieldTypeAlways presentDescription
schemasarray of stringnoThe SCIM schemas of the message. Accepted and not checked.
userNamestringyesThe 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.
externalIdstringnoThe identity provider's own id for the person. Trimmed, and cut to 300 characters.
nameobjectnoThe person's name. formatted and other parts are ignored.
name.givenNamestringnoFirst name. Trimmed, and cut to 200 characters.
name.familyNamestringnoLast name. Trimmed, and cut to 200 characters.
displayNamestringnoThe name to show. Trimmed, and cut to 200 characters. Used as the name of a newly created Nullgap account.
emailsarray of objectnoEmail 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[].valuestringyesAn email address.
emails[].typestringnoThe kind of address, for example work.
emails[].primaryboolean or stringnoTrue for the main address. The text "true" or "false" is accepted too.
activeboolean or stringnoTrue 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.

FieldTypeAlways presentDescription
schemasarray of stringyesThe SCIM schemas this message follows. Always this one value.
idstringyesNullgap's id for the SCIM user.
externalIdstringnoThe identity provider's own id for the person. Left out when none was sent.
userNamestringyesThe sign-in name, as the identity provider sent it.
nameobjectyesThe person's name.
name.givenNamestringyesFirst name. Empty when not sent.
name.familyNamestringyesLast name. Empty when not sent.
name.formattedstringyesFirst and last name joined by a space. Worked out by Nullgap; it cannot be set.
displayNamestringyesThe name to show. Empty when not sent.
emailsarray of objectyesAlways exactly one entry, which repeats userName. Addresses sent in emails are not stored.
emails[].valuestringyesThe same text as userName.
emails[].typestringyesAlways work.
emails[].primarybooleanyesAlways true.
activebooleanyesTrue when the person has a membership of the organisation through provisioning.
metaobjectyesSCIM bookkeeping for the resource.
meta.resourceTypestringyesThe kind of SCIM resource.
meta.createdstringyesWhen the SCIM user was created.
meta.lastModifiedstringyesWhen it was last changed.
meta.locationstringyesThe 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.

FieldTypeAlways presentDescription
schemasarray of stringnoThe SCIM schemas of the message. Accepted and not checked.
userNamestringnoThe 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.
externalIdstringnoThe identity provider's own id for the person. Trimmed, and cut to 300 characters.
nameobjectnoThe person's name. formatted and other parts are ignored.
name.givenNamestringnoFirst name. Trimmed, and cut to 200 characters.
name.familyNamestringnoLast name. Trimmed, and cut to 200 characters.
displayNamestringnoThe name to show. Trimmed, and cut to 200 characters. Used as the name of a newly created Nullgap account.
emailsarray of objectnoEmail 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[].valuestringyesAn email address.
emails[].typestringnoThe kind of address, for example work.
emails[].primaryboolean or stringnoTrue for the main address. The text "true" or "false" is accepted too.
activeboolean or stringnoTrue 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.

FieldTypeAlways presentDescription
schemasarray of stringyesMust include urn:ietf:params:scim:api:messages:2.0:PatchOp.
Operationsarray of objectyesThe changes, applied together as one update.
Operations[].opstringyesWhat 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[].pathstringnoThe 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[].valueanynoThe 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.

FieldTypeAlways presentDescription
schemasarray of stringyesThe SCIM schemas this message follows. Always this one value.
totalResultsintegeryesHow many resources match in all.
startIndexintegeryesThe position of the first resource returned, counting from 1.
itemsPerPageintegeryesHow many resources are in this answer.
Resourcesarray of objectyesAlways empty.

#Error

Every failure has this shape, with a matching HTTP status.

FieldTypeAlways presentDescription
errorobjectyes
error.codestringyesA short, stable name for the failure. Branch on this, not on the message.
error.messagestringyesOne sentence for a person.
error.requestIdstringyesThe id of this request, also sent as the X-Request-Id header. Quote it when you ask for help.

Nullgap documentation