Nullgap.dev Docs

API reference

Single sign-on

Configure OpenID Connect or SAML sign-in and verify e-mail domains.

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 single sign-on settingsGET /api/orgs/{org}/ssoadmin
Save single sign-on settingsPUT /api/orgs/{org}/ssoconsole only (owner)
Remove single sign-onDELETE /api/orgs/{org}/ssoconsole only (owner)
Test single sign-on settingsPOST /api/orgs/{org}/sso/testconsole only (owner)
Verify an email domainPOST /api/orgs/{org}/sso/domains/verifyconsole only (owner)

#Get single sign-on settings

GET /api/orgs/{org}/sso

Returns the organisation's single sign-on configuration, or null when none has been saved. The client secret is never returned, only whether one is stored.

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/sso"

Answer (200, application/json)

{
  "enabled": true,
  "protocol": "oidc",
  "issuer": "https://idp.acme.example",
  "clientId": "nullgap-console",
  "hasClientSecret": true,
  "allowedDomains": [
    "acme.example"
  ],
  "domains": [
    {
      "domain": "acme.example",
      "status": "verified",
      "recordName": "_nullgap-challenge.acme.example",
      "recordValue": "nullgap-domain-verification=Hk3vYp0Zr8sT1uWx5aBc7dEf9gJmNq2L",
      "verifiedAt": "2026-10-03T10:00:00.000Z",
      "lastCheckedAt": "2026-11-16T03:00:00.000Z",
      "failingSince": "2026-11-15T03:00:00.000Z",
      "legacyUntil": "2026-12-01T00:00:00.000Z"
    }
  ],
  "domainVerification": "dns",
  "defaultRole": "member",
  "requireSso": false,
  "trustUnverifiedEmail": false,
  "loginUrl": "https://app.nullgap.dev/api/auth/sso/start?org=acme",
  "redirectUri": "https://app.nullgap.dev/api/auth/sso/callback",
  "saml": {
    "idpEntityId": "https://idp.acme.example/saml/metadata",
    "idpSsoUrl": "https://idp.acme.example/saml/sso",
    "certificates": [
      {
        "fingerprint": "3B:7A:10:9C:5E:44:D2:81:0F:6B:A3:27:C8:19:EE:50:72:4D:B6:0A:95:3F:18:E7:2C:61:D4:8B:07:F9:AE:13",
        "subject": "CN=acme-idp",
        "notAfter": "2028-06-30T23:59:59.000Z"
      }
    ],
    "sp": {
      "entityId": "https://app.nullgap.dev/api/auth/saml/metadata/org_5d2e8a1c9b40",
      "acsUrl": "https://app.nullgap.dev/api/auth/saml/acs",
      "metadataUrl": "https://app.nullgap.dev/api/auth/saml/metadata/org_5d2e8a1c9b40"
    }
  },
  "updatedAt": "2026-11-10T14:05:00.000Z"
}

#Save single sign-on settings

PUT /api/orgs/{org}/sso

Creates the configuration, or changes the fields sent and keeps the rest. A new configuration starts switched off, with OpenID Connect and the role member. Turning single sign-on on needs a complete set-up for the chosen protocol (OpenID Connect: issuer, client id and client secret; SAML: entity ID, sign-in address and a signing certificate) and at least one allowed domain. A new domain must then be verified with a DNS record before anyone can sign in with it. Switching single sign-on off, or pointing it at another identity provider, signs out everyone who signed in through it; removing a domain signs out the people on that domain.

Who may call it: A signed-in owner in the console. No API key may call it.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
protocolstringnoWhich protocol sign-in uses. A new configuration starts as oidc. Settings for the other protocol are kept, so one can be prepared before switching.
issuerstringnoOpenID Connect: the issuer address. Must be an https address on a public host, without a user name or password. Trailing slashes are removed.
clientIdstringnoOpenID Connect: the client id registered at the identity provider.
clientSecretstringnoOpenID Connect: the client secret. Write-only: it is stored encrypted and never returned. Leave it out to keep the stored one.
samlMetadataXmlstringnoSAML: the identity provider's metadata document, as text. It must describe exactly one identity provider, with an HTTP-Redirect sign-in service and at least one signing certificate. It fills the entity ID, sign-in address and certificates; the three fields below, when sent in the same request, override what it says. Nullgap never fetches metadata from an address.
samlIdpEntityIdstringnoSAML: the identity provider's entity ID.
samlIdpSsoUrlstringnoSAML: where sign-in requests are sent. Must be an https address without a user name or password.
samlCertificatesarray of stringnoSAML: the identity provider's signing certificates. Replaces the stored set; duplicates are dropped. At most three. Each entry is one X.509 certificate of up to 8000 characters, as PEM or as its bare base64 body; an entry that does not parse as a certificate is refused. samlMetadataXml is the other way to supply them.
allowedDomainsarray of stringnoThe email domains whose people may sign in. Replaces the whole list. A newly added domain starts unverified. Removing a domain gives up its proof and signs out the people on it.
defaultRolestringnoThe role given to someone who joins through single sign-on or provisioning. A new configuration starts as member.
enabledbooleannoTurn single sign-on on or off. Turning it on needs a complete set-up for the chosen protocol and at least one allowed domain. Turning it off signs out everyone who signed in through it.
requireSsobooleannoMake members sign in through single sign-on. Needs single sign-on to be on, at least one verified domain, and multi-factor sign-in on your own account.
trustUnverifiedEmailbooleannoAccept an email address the OpenID Connect provider did not mark as verified.

Answer (200, application/json)

A SsoConfig object.

{
  "enabled": true,
  "protocol": "oidc",
  "issuer": "https://idp.acme.example",
  "clientId": "nullgap-console",
  "hasClientSecret": true,
  "allowedDomains": [
    "acme.example"
  ],
  "domains": [
    {
      "domain": "acme.example",
      "status": "verified",
      "recordName": "_nullgap-challenge.acme.example",
      "recordValue": "nullgap-domain-verification=Hk3vYp0Zr8sT1uWx5aBc7dEf9gJmNq2L",
      "verifiedAt": "2026-10-03T10:00:00.000Z",
      "lastCheckedAt": "2026-11-16T03:00:00.000Z",
      "failingSince": "2026-11-15T03:00:00.000Z",
      "legacyUntil": "2026-12-01T00:00:00.000Z"
    }
  ],
  "domainVerification": "dns",
  "defaultRole": "member",
  "requireSso": false,
  "trustUnverifiedEmail": false,
  "loginUrl": "https://app.nullgap.dev/api/auth/sso/start?org=acme",
  "redirectUri": "https://app.nullgap.dev/api/auth/sso/callback",
  "saml": {
    "idpEntityId": "https://idp.acme.example/saml/metadata",
    "idpSsoUrl": "https://idp.acme.example/saml/sso",
    "certificates": [
      {
        "fingerprint": "3B:7A:10:9C:5E:44:D2:81:0F:6B:A3:27:C8:19:EE:50:72:4D:B6:0A:95:3F:18:E7:2C:61:D4:8B:07:F9:AE:13",
        "subject": "CN=acme-idp",
        "notAfter": "2028-06-30T23:59:59.000Z"
      }
    ],
    "sp": {
      "entityId": "https://app.nullgap.dev/api/auth/saml/metadata/org_5d2e8a1c9b40",
      "acsUrl": "https://app.nullgap.dev/api/auth/saml/acs",
      "metadataUrl": "https://app.nullgap.dev/api/auth/saml/metadata/org_5d2e8a1c9b40"
    }
  },
  "updatedAt": "2026-11-10T14:05:00.000Z"
}

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.
400bad_requestA field has the wrong type, is blank or too long; an address is not a valid https address or the issuer is not on a public host; the SAML metadata or a certificate could not be read; a domain is not one an organisation can own; or the result would be single sign-on switched on without a complete set-up or without an allowed domain, or required while switched off.
400verify_domain_firstrequireSso is being turned on and no allowed domain has been verified yet.
400enrol_firstrequireSso is on and your own account has no second factor. It is the owner's way in if the identity provider is unavailable.

#Remove single sign-on

DELETE /api/orgs/{org}/sso

Deletes the configuration, gives up the organisation's proof of its domains, and signs out everyone who signed in through single sign-on. Adding a domain back later means verifying it again. Succeeds even when nothing was configured. A SCIM token, if one exists, is not removed, but creating, activating or re-addressing users through it is refused until single sign-on is configured again.

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.

#Test single sign-on settings

POST /api/orgs/{org}/sso/test

Checks the saved settings without signing anyone in. For OpenID Connect, Nullgap fetches the identity provider's discovery document from the saved issuer. For SAML, it checks that the entity ID, sign-in address and certificate are present and that at least one certificate has not expired; it does not contact the identity provider. The call answers 200 whether the check passes or not: read ok. 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 SsoTestResult object.

{
  "ok": true,
  "message": "The identity provider answered and its configuration is valid."
}

#Verify an email domain

POST /api/orgs/{org}/sso/domains/verify

Looks up the DNS TXT record that proves the organisation controls one of its allowed domains, and marks the domain verified when it is there. The record to create is in the domains list of the configuration: a TXT record named _nullgap-challenge.<domain> with the value shown. The call answers 200 whether the record was found or not: read verified and message. A domain can be verified by one organisation only. Calling it for a domain that is already verified checks the record again. Limited to 10 attempts a minute for each organisation.

Who may call it: A signed-in owner in the console. No API key may call it.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
domainstringyesA domain that is already on the saved allowedDomains list. A leading @ is removed and the name is lower-cased.

Answer (200, application/json)

A SsoDomainVerifyResult object.

{
  "verified": true,
  "message": "The record was found. This domain is verified.",
  "sso": {
    "enabled": true,
    "protocol": "oidc",
    "issuer": "https://idp.acme.example",
    "clientId": "nullgap-console",
    "hasClientSecret": true,
    "allowedDomains": [
      "acme.example"
    ],
    "domains": [
      {
        "domain": "acme.example",
        "status": "verified",
        "recordName": "_nullgap-challenge.acme.example",
        "recordValue": "nullgap-domain-verification=Hk3vYp0Zr8sT1uWx5aBc7dEf9gJmNq2L",
        "verifiedAt": "2026-10-03T10:00:00.000Z",
        "lastCheckedAt": "2026-11-16T03:00:00.000Z",
        "failingSince": "2026-11-15T03:00:00.000Z",
        "legacyUntil": "2026-12-01T00:00:00.000Z"
      }
    ],
    "domainVerification": "dns",
    "defaultRole": "member",
    "requireSso": false,
    "trustUnverifiedEmail": false,
    "loginUrl": "https://app.nullgap.dev/api/auth/sso/start?org=acme",
    "redirectUri": "https://app.nullgap.dev/api/auth/sso/callback",
    "saml": {
      "idpEntityId": "https://idp.acme.example/saml/metadata",
      "idpSsoUrl": "https://idp.acme.example/saml/sso",
      "certificates": [
        {
          "fingerprint": "3B:7A:10:9C:5E:44:D2:81:0F:6B:A3:27:C8:19:EE:50:72:4D:B6:0A:95:3F:18:E7:2C:61:D4:8B:07:F9:AE:13",
          "subject": "CN=acme-idp",
          "notAfter": "2028-06-30T23:59:59.000Z"
        }
      ],
      "sp": {
        "entityId": "https://app.nullgap.dev/api/auth/saml/metadata/org_5d2e8a1c9b40",
        "acsUrl": "https://app.nullgap.dev/api/auth/saml/acs",
        "metadataUrl": "https://app.nullgap.dev/api/auth/saml/metadata/org_5d2e8a1c9b40"
      }
    },
    "updatedAt": "2026-11-10T14:05:00.000Z"
  }
}

Errors specific to this call

StatusCodeWhen
404not_foundThe domain is not on the saved list of allowed domains. Save it first.
400bad_requestdomain is missing, not text, blank or longer than 253 characters.
429rate_limitedThe organisation made more than 10 verification attempts in a minute.

#Objects

The objects the operations above take and return.

#SsoConfigBody

The settings to change. Every field is optional; a field left out keeps its stored value. For OpenID Connect send issuer, clientId and clientSecret; for SAML send protocol: "saml" with either samlMetadataXml or the entity ID, sign-in address and certificates.

FieldTypeAlways presentDescription
protocolstringnoWhich protocol sign-in uses. A new configuration starts as oidc. Settings for the other protocol are kept, so one can be prepared before switching.
issuerstringnoOpenID Connect: the issuer address. Must be an https address on a public host, without a user name or password. Trailing slashes are removed.
clientIdstringnoOpenID Connect: the client id registered at the identity provider.
clientSecretstringnoOpenID Connect: the client secret. Write-only: it is stored encrypted and never returned. Leave it out to keep the stored one.
samlMetadataXmlstringnoSAML: the identity provider's metadata document, as text. It must describe exactly one identity provider, with an HTTP-Redirect sign-in service and at least one signing certificate. It fills the entity ID, sign-in address and certificates; the three fields below, when sent in the same request, override what it says. Nullgap never fetches metadata from an address.
samlIdpEntityIdstringnoSAML: the identity provider's entity ID.
samlIdpSsoUrlstringnoSAML: where sign-in requests are sent. Must be an https address without a user name or password.
samlCertificatesarray of stringnoSAML: the identity provider's signing certificates. Replaces the stored set; duplicates are dropped. At most three. Each entry is one X.509 certificate of up to 8000 characters, as PEM or as its bare base64 body; an entry that does not parse as a certificate is refused. samlMetadataXml is the other way to supply them.
allowedDomainsarray of stringnoThe email domains whose people may sign in. Replaces the whole list. A newly added domain starts unverified. Removing a domain gives up its proof and signs out the people on it.
defaultRolestringnoThe role given to someone who joins through single sign-on or provisioning. A new configuration starts as member.
enabledbooleannoTurn single sign-on on or off. Turning it on needs a complete set-up for the chosen protocol and at least one allowed domain. Turning it off signs out everyone who signed in through it.
requireSsobooleannoMake members sign in through single sign-on. Needs single sign-on to be on, at least one verified domain, and multi-factor sign-in on your own account.
trustUnverifiedEmailbooleannoAccept an email address the OpenID Connect provider did not mark as verified.

#SsoConfig

An organisation's single sign-on configuration.

FieldTypeAlways presentDescription
enabledbooleanyesTrue when people can sign in through the identity provider.
protocolstringyesoidc: OpenID Connect. saml: SAML 2.0, started from Nullgap (sign-in started at the identity provider is not accepted).
issuerstringyesThe OpenID Connect issuer address, without a trailing slash. Empty when not set.
clientIdstringyesThe OpenID Connect client id. Empty when not set.
hasClientSecretbooleanyesTrue when a client secret is stored. The secret itself is never returned.
allowedDomainsarray of stringyesThe email domains whose people may sign in through single sign-on.
domainsarray of SsoDomainyesOne entry per allowed domain, in the same order, with its verification state.
domainVerificationstringyesdns: each domain must be proved with a DNS record before anyone can sign in with it. operator-trusted: the operator of this installation has switched the proof off (single-tenant installations only).
defaultRolestringyesThe role given to someone who joins through single sign-on or provisioning. Never owner. One of: admin, member.
requireSsobooleanyesTrue when members must sign in through single sign-on. Owners with multi-factor sign-in keep another way in.
trustUnverifiedEmailbooleanyesTrue to accept an email address the OpenID Connect provider did not mark as verified. Some providers never send that mark.
loginUrlstringyesWhere to send people to sign in.
redirectUristringyesOpenID Connect: the redirect address to register with the identity provider.
samlSamlConfigyes
updatedAtstring or nullyesWhen the configuration was last saved.

#SsoTestResult

FieldTypeAlways presentDescription
okbooleanyesTrue when the saved settings passed the check.
messagestringyesThe outcome in plain words, including what to fix when the check did not pass.

#SsoDomainVerifyResult

The outcome of one verification attempt, with the configuration as it stands afterwards.

FieldTypeAlways presentDescription
verifiedbooleanyesTrue when the DNS record was found and the domain is now verified for this organisation.
messagestringyesThe outcome in plain words: verified, record not found, record found with another value, no answer from DNS, or domain already verified by another workspace.
ssoSsoConfigyes

#SsoDomain

One allowed email domain, whether the organisation has proved it controls it, and the DNS record that proves it.

FieldTypeAlways presentDescription
domainstringyesThe email domain, lower case.
statusstringyesverified: the DNS record was found, people on this domain can sign in and join. pending: nobody can sign in with this domain yet. legacy: the domain was allowed before verification existed; until legacyUntil people who are already members can still sign in, nobody new can join, and after that it behaves like pending.
recordNamestringyesThe name of the DNS TXT record to create.
recordValuestringyesThe exact value the TXT record must have.
verifiedAtstring or nullyesWhen the record was first found. Null while unverified.
lastCheckedAtstring or nullyesWhen the record was last looked up with a definite answer. Null if never.
failingSincestring or nullyesSet while a verified domain's record is missing. Verification ends if it stays missing for seven days. Null otherwise.
legacyUntilstring or nullyesWhen the grace period of a legacy domain ends. Null for any other status.

#SamlConfig

The SAML settings. Present whatever the protocol, so SAML can be prepared before switching to it.

FieldTypeAlways presentDescription
idpEntityIdstringyesThe identity provider's entity ID, which is the issuer of its assertions. Empty until set.
idpSsoUrlstringyesWhere sign-in requests are sent (HTTP-Redirect binding). Empty until set.
certificatesarray of SamlCertificateyesThe signing certificates in use. More than one during a rotation; at most three.
spobjectyesWhat to enter at the identity provider.
sp.entityIdstringyesNullgap's entity ID for this organisation. It is the audience of every assertion.
sp.acsUrlstringyesThe assertion consumer service: where the identity provider posts its answer (HTTP-POST binding).
sp.metadataUrlstringyesWhere Nullgap's SAML metadata can be downloaded. The same address as entityId.

#SamlCertificate

A certificate the identity provider signs with. Public information.

FieldTypeAlways presentDescription
fingerprintstringyesThe SHA-256 fingerprint, as colon-separated hexadecimal. unreadable if the stored certificate can no longer be read.
subjectstringyesThe certificate's subject.
notAfterstringyesWhen the certificate expires.

Nullgap documentation