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.
| Operation | Method and path | Who may call it |
|---|---|---|
| Get single sign-on settings | GET /api/orgs/{org}/sso | admin |
| Save single sign-on settings | PUT /api/orgs/{org}/sso | console only (owner) |
| Remove single sign-on | DELETE /api/orgs/{org}/sso | console only (owner) |
| Test single sign-on settings | POST /api/orgs/{org}/sso/test | console only (owner) |
| Verify an email domain | POST /api/orgs/{org}/sso/domains/verify | console 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
| 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/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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
protocol | string | no | Which protocol sign-in uses. A new configuration starts as oidc. Settings for the other protocol are kept, so one can be prepared before switching. |
issuer | string | no | OpenID Connect: the issuer address. Must be an https address on a public host, without a user name or password. Trailing slashes are removed. |
clientId | string | no | OpenID Connect: the client id registered at the identity provider. |
clientSecret | string | no | OpenID Connect: the client secret. Write-only: it is stored encrypted and never returned. Leave it out to keep the stored one. |
samlMetadataXml | string | no | SAML: 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. |
samlIdpEntityId | string | no | SAML: the identity provider's entity ID. |
samlIdpSsoUrl | string | no | SAML: where sign-in requests are sent. Must be an https address without a user name or password. |
samlCertificates | array of string | no | SAML: 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. |
allowedDomains | array of string | no | The 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. |
defaultRole | string | no | The role given to someone who joins through single sign-on or provisioning. A new configuration starts as member. |
enabled | boolean | no | Turn 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. |
requireSso | boolean | no | Make 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. |
trustUnverifiedEmail | boolean | no | Accept 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
| 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 | bad_request | A 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. |
| 400 | verify_domain_first | requireSso is being turned on and no allowed domain has been verified yet. |
| 400 | enrol_first | requireSso 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
| 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. |
#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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
domain | string | yes | A 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | The domain is not on the saved list of allowed domains. Save it first. |
| 400 | bad_request | domain is missing, not text, blank or longer than 253 characters. |
| 429 | rate_limited | The 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.
| Field | Type | Always present | Description |
|---|---|---|---|
protocol | string | no | Which protocol sign-in uses. A new configuration starts as oidc. Settings for the other protocol are kept, so one can be prepared before switching. |
issuer | string | no | OpenID Connect: the issuer address. Must be an https address on a public host, without a user name or password. Trailing slashes are removed. |
clientId | string | no | OpenID Connect: the client id registered at the identity provider. |
clientSecret | string | no | OpenID Connect: the client secret. Write-only: it is stored encrypted and never returned. Leave it out to keep the stored one. |
samlMetadataXml | string | no | SAML: 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. |
samlIdpEntityId | string | no | SAML: the identity provider's entity ID. |
samlIdpSsoUrl | string | no | SAML: where sign-in requests are sent. Must be an https address without a user name or password. |
samlCertificates | array of string | no | SAML: 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. |
allowedDomains | array of string | no | The 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. |
defaultRole | string | no | The role given to someone who joins through single sign-on or provisioning. A new configuration starts as member. |
enabled | boolean | no | Turn 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. |
requireSso | boolean | no | Make 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. |
trustUnverifiedEmail | boolean | no | Accept an email address the OpenID Connect provider did not mark as verified. |
#SsoConfig
An organisation's single sign-on configuration.
| Field | Type | Always present | Description |
|---|---|---|---|
enabled | boolean | yes | True when people can sign in through the identity provider. |
protocol | string | yes | oidc: OpenID Connect. saml: SAML 2.0, started from Nullgap (sign-in started at the identity provider is not accepted). |
issuer | string | yes | The OpenID Connect issuer address, without a trailing slash. Empty when not set. |
clientId | string | yes | The OpenID Connect client id. Empty when not set. |
hasClientSecret | boolean | yes | True when a client secret is stored. The secret itself is never returned. |
allowedDomains | array of string | yes | The email domains whose people may sign in through single sign-on. |
domains | array of SsoDomain | yes | One entry per allowed domain, in the same order, with its verification state. |
domainVerification | string | yes | dns: 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). |
defaultRole | string | yes | The role given to someone who joins through single sign-on or provisioning. Never owner. One of: admin, member. |
requireSso | boolean | yes | True when members must sign in through single sign-on. Owners with multi-factor sign-in keep another way in. |
trustUnverifiedEmail | boolean | yes | True to accept an email address the OpenID Connect provider did not mark as verified. Some providers never send that mark. |
loginUrl | string | yes | Where to send people to sign in. |
redirectUri | string | yes | OpenID Connect: the redirect address to register with the identity provider. |
saml | SamlConfig | yes | |
updatedAt | string or null | yes | When the configuration was last saved. |
#SsoTestResult
| Field | Type | Always present | Description |
|---|---|---|---|
ok | boolean | yes | True when the saved settings passed the check. |
message | string | yes | The 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.
| Field | Type | Always present | Description |
|---|---|---|---|
verified | boolean | yes | True when the DNS record was found and the domain is now verified for this organisation. |
message | string | yes | The outcome in plain words: verified, record not found, record found with another value, no answer from DNS, or domain already verified by another workspace. |
sso | SsoConfig | yes |
#SsoDomain
One allowed email domain, whether the organisation has proved it controls it, and the DNS record that proves it.
| Field | Type | Always present | Description |
|---|---|---|---|
domain | string | yes | The email domain, lower case. |
status | string | yes | verified: 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. |
recordName | string | yes | The name of the DNS TXT record to create. |
recordValue | string | yes | The exact value the TXT record must have. |
verifiedAt | string or null | yes | When the record was first found. Null while unverified. |
lastCheckedAt | string or null | yes | When the record was last looked up with a definite answer. Null if never. |
failingSince | string or null | yes | Set while a verified domain's record is missing. Verification ends if it stays missing for seven days. Null otherwise. |
legacyUntil | string or null | yes | When 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.
| Field | Type | Always present | Description |
|---|---|---|---|
idpEntityId | string | yes | The identity provider's entity ID, which is the issuer of its assertions. Empty until set. |
idpSsoUrl | string | yes | Where sign-in requests are sent (HTTP-Redirect binding). Empty until set. |
certificates | array of SamlCertificate | yes | The signing certificates in use. More than one during a rotation; at most three. |
sp | object | yes | What to enter at the identity provider. |
sp.entityId | string | yes | Nullgap's entity ID for this organisation. It is the audience of every assertion. |
sp.acsUrl | string | yes | The assertion consumer service: where the identity provider posts its answer (HTTP-POST binding). |
sp.metadataUrl | string | yes | Where Nullgap's SAML metadata can be downloaded. The same address as entityId. |
#SamlCertificate
A certificate the identity provider signs with. Public information.
| Field | Type | Always present | Description |
|---|---|---|---|
fingerprint | string | yes | The SHA-256 fingerprint, as colon-separated hexadecimal. unreadable if the stored certificate can no longer be read. |
subject | string | yes | The certificate's subject. |
notAfter | string | yes | When the certificate expires. |
Nullgap documentation