Reference

Auth API

Sessions.

21 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

GET/auth-providers

Configured single-sign-on providers (instance admin)

Response 200 · OK · application/json

AdminProvidersOutputBody

ProviderBody[] | nullrequired

Errors

401Unauthorized
403Forbidden
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/auth-providers

Add a single-sign-on provider (instance admin)

OIDC issuers are checked through discovery (/.well-known/openid-configuration) before saving.

Request body · application/json · required

ProviderInputBody

allowedDomainsstring[] | null
clientIdstringrequired
clientSecretstring
Write-only. Required on create; empty on update keeps the stored secret
enabledboolean
idstring
Create only: the ID the provider gets, so its callback URL (/api/v1/auth/oidc/{id}/callback) can be registered at the identity provider before saving. Generated when omitted; 409 provider_id_taken when in use
issuerUrlstring
kindenum: oidc | githubrequired
namestringrequired
scopesstring[] | null
trustMfaboolean

Response 201 · Created · application/json

ProviderBody

allowedDomainsstring[] | nullrequired
Empty allows any verified email
clientIdstringrequired
createdAtstring (date-time)required
enabledbooleanrequired
idstringrequired
issuerUrlstringrequired
OIDC issuer; for GitHub an optional Enterprise Server base URL
kindenum: oidc | githubrequired
namestringrequired
redirectUristringrequired
Register this callback URL at the provider
scopesstring[] | nullrequired
trustMfabooleanrequired
Skip the local 2FA step when the provider asserts MFA (amr claim)

Errors

401Unauthorized
403Forbidden
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/auth-providers/{id}

Replace a single-sign-on provider's settings (instance admin)

Parameter	In	Type	Description
`id`required	path	string

Request body · application/json · required

ProviderInputBody

allowedDomainsstring[] | null
clientIdstringrequired
clientSecretstring
Write-only. Required on create; empty on update keeps the stored secret
enabledboolean
idstring
Create only: the ID the provider gets, so its callback URL (/api/v1/auth/oidc/{id}/callback) can be registered at the identity provider before saving. Generated when omitted; 409 provider_id_taken when in use
issuerUrlstring
kindenum: oidc | githubrequired
namestringrequired
scopesstring[] | null
trustMfaboolean

Response 200 · OK · application/json

ProviderBody

allowedDomainsstring[] | nullrequired
Empty allows any verified email
clientIdstringrequired
createdAtstring (date-time)required
enabledbooleanrequired
idstringrequired
issuerUrlstringrequired
OIDC issuer; for GitHub an optional Enterprise Server base URL
kindenum: oidc | githubrequired
namestringrequired
redirectUristringrequired
Register this callback URL at the provider
scopesstring[] | nullrequired
trustMfabooleanrequired
Skip the local 2FA step when the provider asserts MFA (amr claim)

Errors

401Unauthorized
403Forbidden
404Not Found
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/auth-providers/{id}

Remove a single-sign-on provider and its linked identities (instance admin)

Parameter	In	Type	Description
`id`required	path	string

Response 204 · No Content

No body.

Errors

401Unauthorized
403Forbidden
404Not Found
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/auth-settings

Instance sign-in settings (instance admin)

Response 200 · OK · application/json

AuthSettingsBody

allowOpenSignupbooleanrequired
Let anyone create an account through an identity provider without an invite (default off)

Errors

401Unauthorized
403Forbidden
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/auth-settings

Change instance sign-in settings (instance admin)

Request body · application/json · required

AuthSettingsBody

allowOpenSignupbooleanrequired
Let anyone create an account through an identity provider without an invite (default off)

Response 200 · OK · application/json

AuthSettingsBody

allowOpenSignupbooleanrequired
Let anyone create an account through an identity provider without an invite (default off)

Errors

401Unauthorized
403Forbidden
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/auth/2faPublic

What can finish the pending sign-in

Response 200 · OK · application/json

SecondFactorMethodsOutputBody

passkeybooleanrequired
A passkey can finish the sign-in
totpbooleanrequired
An authenticator-app or recovery code can finish the sign-in

Errors

401Unauthorized
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/auth/2faPublic

Finish sign-in with a TOTP or recovery code

Follows a login that answered 401 two_factor_required (or a provider login that redirected to /login?step=2fa). The pending login expires after 5 minutes and after 5 wrong codes; limited to 10 attempts per minute per client IP.

Request body · application/json · required

SecondFactorInputBody

codestringrequired
A 6-digit authenticator code or a recovery code

Response 200 · OK · application/json

MeBody

createdAtstring (date-time)required
emailstringrequired
idstringrequired
instanceAdminbooleanrequired
The first user: manages instance settings
namestringrequired
PrincipalBodyrequired
workspaceIdstringrequired

Errors

401Unauthorizedtwo_factor_required
422Unprocessable Entity
429Too Many Requests
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/auth/2fa/passkeyPublic

Finish sign-in with a passkey as the second factor

The pending login expires after 5 minutes and after 5 wrong answers; limited to 10 attempts per minute per client IP.

Request body · application/json · required

any

Response 200 · OK · application/json

MeBody

createdAtstring (date-time)required
emailstringrequired
idstringrequired
instanceAdminbooleanrequired
The first user: manages instance settings
namestringrequired
PrincipalBodyrequired
workspaceIdstringrequired

Errors

401Unauthorized
422Unprocessable Entity
429Too Many Requests
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/auth/2fa/passkey/optionsPublic

Ask the account's passkeys to finish a pending sign-in

Follows a login that answered 401 two_factor_required. Returns the WebAuthn request options for navigator.credentials.get; the answer goes to POST /auth/2fa/passkey.

Response 200 · OK · application/json

any

Errors

401Unauthorizedtwo_factor_required
409Conflict
429Too Many Requests
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/auth/loginPublic

Sign in with email and password (sets the session cookie)

Limited to 10 attempts per minute per client IP.

Request body · application/json · required

LoginInputBody

emailstringrequired
passwordstringrequired

Response 200 · OK · application/json

MeBody

createdAtstring (date-time)required
emailstringrequired
idstringrequired
instanceAdminbooleanrequired
The first user: manages instance settings
namestringrequired
PrincipalBodyrequired
workspaceIdstringrequired

Errors

401Unauthorized
422Unprocessable Entity
429Too Many Requests
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/auth/logoutPublic

Destroy the current session

Response 204 · No Content

No body.

GET/auth/oidc/{providerId}/callbackPublic

OAuth/OIDC redirect target of the identity provider

Completes the sign-in and redirects to / (or /login?step=2fa / /login?error=<code>).

Parameter	In	Type
`providerId`required	path	string
`code`	query	string
`state`	query	string
`error`	query	string

Response 302 · Found

No body.

GET/auth/oidc/{providerId}/startPublic

Redirect to the identity provider

Parameter	In	Type	Description
`providerId`required	path	string
`invite`	query	string	Team invite token that authorises sign-up of a new account

Response 302 · Found

No body.

Errors

404Not Found
422Unprocessable Entity
429Too Many Requests
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/auth/passkey/loginPublic

Finish a passwordless sign-in with a passkey (sets the session cookie)

A passkey verified on the authenticator (PIN or biometric) counts as two factors: the session is second-factor verified and no code is asked for.

Request body · application/json · required

any

Response 200 · OK · application/json

MeBody

createdAtstring (date-time)required
emailstringrequired
idstringrequired
instanceAdminbooleanrequired
The first user: manages instance settings
namestringrequired
PrincipalBodyrequired
workspaceIdstringrequired

Errors

401Unauthorized
422Unprocessable Entity
429Too Many Requests
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/auth/passkey/optionsPublic

Start a passwordless sign-in with a passkey

Returns the WebAuthn request options for navigator.credentials.get; the answer goes to POST /auth/passkey/login. The options expire after 5 minutes. Limited to 10 attempts per minute per client IP.

Response 200 · OK · application/json

any

Errors

422Unprocessable Entity
429Too Many Requests
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/auth/password-resetPublic

Whether password reset by email is available

Response 200 · OK · application/json

PasswordResetStatusOutputBody

availablebooleanrequired
Whether the login page may offer Forgot password: an email can be sent and the control plane has a public URL

POST/auth/password-reset/confirmPublic

Set a new password with a reset link

Single use. Ends every session of the account; two-factor authentication still applies at the next sign-in. 400 invalid_reset_token for an unknown, expired or used link; limited to 10 attempts per minute per client IP.

Request body · application/json · required

PasswordResetConfirmInputBody

passwordstringrequired
tokenstringrequired

Response 204 · No Content

No body.

Errors

400Bad Requestinvalid_reset_token
422Unprocessable Entity
429Too Many Requests
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/auth/password-reset/requestPublic

Email a password reset link

Answers 202 whether or not the account exists, so it cannot be used to find out which emails are registered; accounts that sign in only through an identity provider get no email. The link works once and expires after 30 minutes. Limited to 10 requests per hour per client IP and 3 per hour per email address. 503 password_reset_unavailable when the instance has no SMTP relay or team email channel, or no public URL.

Request body · application/json · required

PasswordResetRequestInputBody

emailstringrequired

Response 202 · Accepted · application/json

PasswordResetRequestOutputBody

statusenum: requestedrequired
Always 'requested': the answer is the same whether or not the account exists

Errors

422Unprocessable Entity
429Too Many Requests
500Internal Server Error
503Service Unavailablepassword_reset_unavailable

Errors are RFC 9457 application/problem+json with a stable code field.

GET/auth/providersPublic

Enabled single-sign-on providers for the login page

Response 200 · OK · application/json

ProvidersOutputBody

PublicProviderBody[] | nullrequired

POST/instance/sign-in-providers/test

Test an OpenID Connect issuer without saving it (instance admin)

Reads /.well-known/openid-configuration of the issuer the way saving a provider does and checks that the document names the same issuer and has the authorization endpoint, token endpoint and key set. Answers 200 either way: ok is false with a specific code and message when the issuer cannot be used.

Request body · application/json · required

TestIssuerInputBody

issuerUrlstringrequired
The OIDC issuer to read the discovery document of

Response 200 · OK · application/json

TestIssuerBody

authorizationEndpointstring
Where people are sent to sign in (on success)
codeenum: invalid_issuer | host_not_found | unreachable | timeout | tls_invalid | discovery_not_found | discovery_invalid | issuer_mismatch | discovery_incomplete
Why the issuer cannot be used (on failure)
issuerstring
The issuer the provider reported (on success)
messagestring
What to fix (on failure)
okbooleanrequired
The issuer serves a usable OpenID configuration

Errors

401Unauthorized
403Forbidden
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.