API Reference
Docs version v1 (main)Nauthera is pre-1.0, in a design-partner program
OAuth 2.0 and OpenID Connect endpoints served on the public listener.
The public HTTP API of nauthera-server. Nauthera is a self-hosted OAuth 2.0 and OpenID Connect identity provider for Kubernetes, written in Go.
The API serves OpenID Connect Discovery 1.0 and RFC 8414 authorization
server metadata, the JSON Web Key Set, the authorization endpoint
(authorization code with PKCE), pushed authorization requests (RFC 9126),
the token endpoint (authorization code, refresh token, client credentials
and device code grants), device authorization (RFC 8628), token
introspection and revocation, UserInfo, RP-initiated logout, dynamic client
registration and management (RFC 7591, RFC 7592), the endpoints behind the
hosted sign-in pages, and the admin API under /v1/admin.
Tokens can be sender-constrained with DPoP (RFC 9449), and authorization responses identify their issuer (RFC 9207), as the OAuth 2.0 Security Best Current Practice (RFC 9700) recommends. Which specifications are implemented, in full or in part, is listed at https://www.nauthera.io/standards.
This reference is generated from the OpenAPI document that nauthera-server is built from, so it describes exactly what the server accepts and returns. Every endpoint page shows a ready-to-run request in cURL, JavaScript, Python and Go, with an example response for each status.
Base URL
Paths are relative to your organization's issuer URL: the server root for the main organization, /orgs/{slug} for every other one (see Organizations). The examples use:
https://auth.example.comhttps://auth.example.com— Production issuer (replace with your issuer.url)http://localhost:8080— Local development (just run)
Authentication
Bearer tokenbearerAuthJWT
A bearer (or DPoP) access token issued by this provider.
HTTP BasicclientSecretBasic
Confidential-client credentials via HTTP Basic (client_secret_basic).
Registration access tokenregistrationAccessToken
The RFC 7592 registration access token for client management.
Initial access tokeninitialAccessToken
The RFC 7591 §1.2 initial access token: an OAuth 2.0 access token carrying the nauthera.clients:register scope, which authorizes calls to the client registration endpoint and supplies the organization the new client is bound to. RFC 7591 §3 makes open (unauthenticated) registration a SHOULD; this deployment deviates deliberately, because every client here belongs to an org and an anonymous registrant has none.
OAuth 2.0oauth2
OAuth 2.0 access tokens used to authorize the admin REST surface
(/v1/admin/**). Two flows are advertised, both minting tokens against
this provider's /token endpoint:
- authorizationCode (PKCE, RFC 7636) — an interactive operator signs
in to their organization's admin-console client (a public PKCE client
auto-provisioned per org) and receives an access token carrying the
granted OAuth scopes (below). The caller's roles are read from
user_org_roleson every request, not taken from the token. - clientCredentials (RFC 6749 §4.4) — a confidential machine-to-machine
admin client exchanges its
client_id/client_secretfor an access token carrying the scopes its registration grants (and any admin roles bound to it through reserved client labels). Used for headless automation of the admin surface.
Authorization on every admin operation is the CONJUNCTION of two
independent checks: the token's scope claim MUST contain the operation's
declared scope (validated via oauthsrv.HasScope) AND the caller MUST
hold the permission the operation declares in its x-permission,
resolved from their roles through a fixed table (internal/rbac). A
token that carries the scope but whose caller lacks the permission — or
the reverse — is rejected. A scope caps what a client may do on its
user's behalf; a permission is what that user may do at all.
x-permissions below is the closed permission vocabulary, and the
server's handlers are held to each operation's declaration by a test.
The users and audit scopes below are org-scoped: a caller acts only
within its own org unless a platform role held in the main org admits it
to every org. The clients, sessions, insights, threats and roles scopes
are the admin dashboard's, registered by every organization's admin console
alone; like every scope they cap what a client may ask for, and the
permission each operation declares does the fine-grained work.
x-permission also declares whether the operation requires a recent
sign-in. A token whose sign-in is older than the deployment allows
(fifteen minutes by default), states none, or lacks a second factor the
deployment requires is answered 401 insufficient_user_authentication,
with an RFC 9470 challenge carrying max_age (and acr_values): sign
in again and replay the call.
Authorization code flow18 scopes
Authorization URL https://auth.example.com/authorize
Token URL https://auth.example.com/token
Refresh URL https://auth.example.com/token
openidOpenID Connect authentication (issue an ID token).
profileBasic profile claims (name, preferred_username, …).
emailEmail-address claims (email, email_verified).
offline_accessIssue a refresh token for long-lived access.
nauthera.orgs:readRead organizations through the admin API (list and get). Pairs with the orgs.read permission: held in an organization, it reads that organization; listing them, and reading any other, takes a platform role held in the main org.
nauthera.orgs:writeCreate, update and delete organizations through the admin API. Pairs with the orgs.write permission, which only a platform role held in the main org grants.
nauthera.users:readRead local users through the admin API (list and get). Pairs with the users.read permission; confined to the caller's own org unless a platform role held in the main org admits it to every org.
nauthera.users:writeCreate, update, delete, suspend, block, reactivate and unlock local users, set their passwords and email them reset links through the admin API. Pairs with the users.create, users.update, users.delete, users.lifecycle or users.credentials permission, whichever the operation declares; confined to the caller's own org unless a platform role held in the main org admits it to every org.
nauthera.audit:readRead the audit log through the admin API. Pairs with the audit.read permission; confined to the caller's own org unless a platform role held in the main org admits it to every org. Platform-scoped records are visible only to a caller who also holds platform.audit.
nauthera.clients:readRead an organization's OIDC clients through the admin API. Pairs with the clients.read permission. Distinct from nauthera.clients:register, which authorizes dynamic client registration and grants no admin authority.
nauthera.sessions:readRead users' sessions through the admin API. Pairs with the sessions.read permission.
nauthera.sessions:writeEnd users' sessions through the admin API. Pairs with the sessions.revoke permission.
nauthera.insights:readRead an organization's insights and alerts through the admin API. Pairs with the insights.read permission.
nauthera.threats:readRead an organization's threat analytics through the admin API. Pairs with the threats.read permission.
nauthera.roles:readRead who holds which role through the admin API. Pairs with the roles.read permission.
nauthera.roles:writeGrant and revoke roles through the admin API. Pairs with the roles.assign permission.
nauthera.brokers:writeInvite, accept, limit and end broker memberships through the admin API. Pairs with the brokers.manage permission.
nauthera.domains:writeClaim, verify and remove email domains through the admin API. Pairs with the domains.manage permission.
Client credentials flow14 scopes
Token URL https://auth.example.com/token
Refresh URL https://auth.example.com/token
nauthera.orgs:readRead organizations through the admin API (list and get). Pairs with the orgs.read permission: held in an organization, it reads that organization; listing them, and reading any other, takes a platform role held in the main org.
nauthera.orgs:writeCreate, update and delete organizations through the admin API. Pairs with the orgs.write permission, which only a platform role held in the main org grants.
nauthera.users:readRead local users through the admin API (list and get). Pairs with the users.read permission; confined to the caller's own org unless a platform role held in the main org admits it to every org.
nauthera.users:writeCreate, update, delete, suspend, block, reactivate and unlock local users, set their passwords and email them reset links through the admin API. Pairs with the users.create, users.update, users.delete, users.lifecycle or users.credentials permission, whichever the operation declares; confined to the caller's own org unless a platform role held in the main org admits it to every org.
nauthera.audit:readRead the audit log through the admin API. Pairs with the audit.read permission; confined to the caller's own org unless a platform role held in the main org admits it to every org. Platform-scoped records are visible only to a caller who also holds platform.audit.
nauthera.clients:readRead an organization's OIDC clients through the admin API. Pairs with the clients.read permission. Distinct from nauthera.clients:register, which authorizes dynamic client registration and grants no admin authority.
nauthera.sessions:readRead users' sessions through the admin API. Pairs with the sessions.read permission.
nauthera.sessions:writeEnd users' sessions through the admin API. Pairs with the sessions.revoke permission.
nauthera.insights:readRead an organization's insights and alerts through the admin API. Pairs with the insights.read permission.
nauthera.threats:readRead an organization's threat analytics through the admin API. Pairs with the threats.read permission.
nauthera.roles:readRead who holds which role through the admin API. Pairs with the roles.read permission.
nauthera.roles:writeGrant and revoke roles through the admin API. Pairs with the roles.assign permission.
nauthera.brokers:writeInvite, accept, limit and end broker memberships through the admin API. Pairs with the brokers.manage permission.
nauthera.domains:writeClaim, verify and remove email domains through the admin API. Pairs with the domains.manage permission.
Permissions21
orgs.readRead organizations.
orgs.writeCreate, update and delete organizations.
users.readRead an organization's users.
users.pii.readRead users' personal data, such as email addresses and attributes.
users.createCreate users.
users.updateChange a user's email address, username and attributes.
users.deleteDelete users.
users.lifecycleSuspend, block, reactivate and unlock users.
users.credentialsSet a user's password and manage their second factors.
users.activityRead what a user did and what was done to them.
sessions.readRead users' sessions.
sessions.revokeEnd users' sessions.
clients.readRead an organization's OIDC clients.
audit.readRead an organization's audit log.
platform.auditRead the platform-scoped audit records, which concern the deployment rather than any one organization, beside an organization's own.
insights.readRead an organization's insights and alerts.
threats.readRead an organization's threat analytics: the attack signals counted from its audit log, against their recommended thresholds.
roles.readRead who holds which role.
roles.assignGrant and revoke roles.
brokers.manageInvite, accept, limit and end broker memberships, which let one organization's clients sign in another's users.
domains.manageClaim, verify and remove the email domains that route a sign-in to an organization.
Endpoints
Discovery
OpenID Connect discovery, AS metadata, and key material.
OAuth2
OAuth2 protocol endpoints (RFC 6749, 7009, 7662, 8628, 9126).
- GET
/authorizeOAuth2 / OIDC authorization endpoint - POST
/authorizeOAuth2 / OIDC authorization endpoint (POST form) - POST
/parPushed Authorization Request - POST
/tokenOAuth2 token endpoint - POST
/device_authorizationDevice Authorization Request - POST
/introspectOAuth2 token introspection - POST
/revokeOAuth2 token revocation
OpenID Connect
OpenID Connect protocol endpoints (OIDC Core, RP-Initiated Logout).
Client Registration
Dynamic client registration and management (RFC 7591, 7592).
Interactive
Browser-facing endpoints backing the hosted auth UI (/ui): password sign-in, local registration, and sign-out. Same-origin JSON; not part of the OAuth2/OIDC wire protocol.
- POST
/v1/auth/sign-inPassword sign-in - POST
/v1/auth/registerLocal account registration - GET
/v1/auth/captchaThe captcha the hosted UI must solve - POST
/v1/auth/password-resetAsk for a password-reset link - POST
/v1/auth/password-reset/confirmSet a new password from a reset link - POST
/v1/auth/invitation/acceptChoose a password from an invitation link - POST
/v1/auth/verify-email/resendAsk for a link that verifies an email address - POST
/v1/auth/verify-email/confirmVerify an email address from a link - POST
/v1/auth/broker/routeRoute an email address to the member organization that owns its domain - GET
/v1/auth/broker/{member}/startBegin a sign-in at a member organization of this broker - GET
/v1/auth/broker/{member}/callbackThe member organization's redirect back to this broker - GET
/v1/auth/federation/{slug}/startBegin a sign-in through an identity provider - GET
/v1/auth/federation/{slug}/callbackThe identity provider's redirect back - POST
/v1/auth/sign-outSign out of the interactive session - POST
/v1/auth/logout/confirmAnswer an RP-initiated logout confirmation - POST
/v1/auth/consentDescribe the pending authorization request - POST
/v1/auth/consent/decisionRecord the user's consent decision - POST
/v1/auth/device/verifyLook up a device authorization by its user code - POST
/v1/auth/device/decisionApprove or deny a device authorization - GET
/v1/auth/mfa/totp/enrollBegin (or re-display) TOTP enrollment - POST
/v1/auth/mfa/totp/activateConfirm and activate TOTP enrollment - POST
/v1/auth/mfa/totp/recovery-ackAcknowledge saved recovery codes and complete enrollment - POST
/v1/auth/mfa/totp/verifyVerify a TOTP code during sign-in - POST
/v1/auth/mfa/email/enrollSend the code that enrolls the email second factor - POST
/v1/auth/mfa/email/activateConfirm and activate the email second factor - POST
/v1/auth/mfa/email/sendSend a sign-in code to the email second factor - POST
/v1/auth/mfa/email/verifyVerify an emailed code during sign-in - POST
/v1/auth/mfa/passkey/registration/optionsBegin a passkey registration ceremony - POST
/v1/auth/mfa/passkey/registration/verifyVerify a passkey registration and enroll the credential - POST
/v1/auth/mfa/passkey/authentication/optionsBegin a passkey authentication ceremony - POST
/v1/auth/mfa/passkey/authentication/verifyVerify a passkey assertion during sign-in - POST
/v1/auth/mfa/passkey/offer/declineDecline the offer to add a passkey and complete the sign-in - POST
/v1/auth/passkey/optionsBegin a passwordless passkey sign-in - POST
/v1/auth/passkey/verifySign in with a passkey and no password - POST
/v1/auth/mfa/recovery-code/verifyRedeem a single-use recovery code during sign-in - POST
/v1/auth/mfa/recovery-codesRegenerate recovery codes - GET
/v1/auth/mfaMFA status for the current session - DELETE
/v1/auth/mfa/totpDisable (remove) the TOTP factor
Admin
Privileged administrative endpoints for managing organizations (orgs) and
their local users (CRUD), versioned under /v1/admin. Authenticated by a
Bearer access token: every operation enforces its declared nauthera.*
scope (via the oauth2 security scheme) IN ADDITION to the permission it
declares in x-permission, which the caller's roles must grant. Organization
endpoints are main-org only; user and audit endpoints are confined to the
caller's own org unless a platform role held in the main org admits them to
every org. All list endpoints use opaque
cursor (keyset) pagination — bound the page with limit, order it with
sort (per-endpoint x-sort-fields), then pass the previous response's
page.next_cursor back as cursor for as long as page.has_more is true.
Not part of the OAuth2/OIDC wire protocol.
- GET
/v1/admin/meGet who the caller is and what they may do - GET
/v1/admin/problemsList what operators could not do for resources in no organization - GET
/v1/admin/problems/{id}Get one problem an operator reported for a resource in no organization - GET
/v1/admin/orgsList organizations - POST
/v1/admin/orgsCreate an organization - GET
/v1/admin/orgs/{slug}Get an organization - PATCH
/v1/admin/orgs/{slug}Update an organization - DELETE
/v1/admin/orgs/{slug}Delete an organization - GET
/v1/admin/orgs/{slug}/themeGet an organization's dashboard theme - GET
/v1/admin/orgs/{slug}/mailGet an organization's email relay - POST
/v1/admin/orgs/{slug}/mail/testSend a test email through an organization's relay - GET
/v1/admin/orgs/{slug}/snapshotCount an organization's users, sessions and clients - GET
/v1/admin/orgs/{slug}/clientsList an organization's OIDC clients - GET
/v1/admin/orgs/{slug}/clients/{id}Get one OIDC client's registered configuration - GET
/v1/admin/orgs/{slug}/clients/{id}/usageCount one OIDC client's daily, monthly and all-time users - GET
/v1/admin/orgs/{slug}/identity-providersList an organization's identity providers - GET
/v1/admin/orgs/{slug}/problemsList what operators could not do for an organization's resources - GET
/v1/admin/orgs/{slug}/problems/{id}Get one problem an operator reported for an organization's resource - GET
/v1/admin/orgs/{slug}/broker-membershipsList an organization's broker memberships - POST
/v1/admin/orgs/{slug}/broker-membershipsInvite an organization to be a member of this broker - DELETE
/v1/admin/orgs/{slug}/broker-memberships/{id}End a broker membership, from either side - POST
/v1/admin/orgs/{slug}/broker-memberships/{id}/acceptAccept a broker's invitation - PUT
/v1/admin/orgs/{slug}/broker-memberships/{id}/clientsChoose which of the broker's clients a membership admits - GET
/v1/admin/orgs/{slug}/email-domainsList an organization's email domain claims - POST
/v1/admin/orgs/{slug}/email-domainsClaim an email domain for an organization - DELETE
/v1/admin/orgs/{slug}/email-domains/{id}Remove an email domain claim - POST
/v1/admin/orgs/{slug}/email-domains/{id}/verifyVerify an email domain claim against its TXT record - GET
/v1/admin/orgs/{slug}/usersList users - POST
/v1/admin/orgs/{slug}/usersCreate a user - GET
/v1/admin/orgs/{slug}/users/{id}Get a user - PATCH
/v1/admin/orgs/{slug}/users/{id}Update a user - DELETE
/v1/admin/orgs/{slug}/users/{id}Delete a user - PUT
/v1/admin/orgs/{slug}/users/{id}/passwordSet a user's password - POST
/v1/admin/orgs/{slug}/users/{id}/suspendSuspend a user - POST
/v1/admin/orgs/{slug}/users/{id}/blockBlock a user - POST
/v1/admin/orgs/{slug}/users/{id}/reactivateReactivate a user - POST
/v1/admin/orgs/{slug}/users/{id}/unlockUnlock a user - POST
/v1/admin/orgs/{slug}/users/{id}/password-changeRequire a user to set a new password at their next sign-in - POST
/v1/admin/orgs/{slug}/users/{id}/password-resetEmail a user a password reset link - POST
/v1/admin/orgs/{slug}/users/{id}/invitationSend a user a new invitation - GET
/v1/admin/orgs/{slug}/users/{id}/devicesList a user's known browsers and networks - DELETE
/v1/admin/orgs/{slug}/users/{id}/devices/rememberedForget a user's browsers remembered for their second factor - GET
/v1/admin/orgs/{slug}/users/{id}/identitiesList the identity provider accounts linked to a user - GET
/v1/admin/orgs/{slug}/users/{id}/rolesList a user's roles - PUT
/v1/admin/orgs/{slug}/users/{id}/roles/{role}Grant a user a role - DELETE
/v1/admin/orgs/{slug}/users/{id}/roles/{role}Revoke a user's role - GET
/v1/admin/orgs/{slug}/users/{id}/session-historyList a user's ended sessions - DELETE
/v1/admin/orgs/{slug}/users/{id}/sessionsEnd every session of a user - GET
/v1/admin/orgs/{slug}/sessionsList an organization's active sessions - DELETE
/v1/admin/orgs/{slug}/sessions/{sid}End one session - GET
/v1/admin/orgs/{slug}/audit-eventsList audit events - GET
/v1/admin/orgs/{slug}/audit-events/tailFollow the audit log - GET
/v1/admin/orgs/{slug}/audit-events/countsCount audit events over time - GET
/v1/admin/orgs/{slug}/audit-events/topRank the subjects behind audit events - GET
/v1/admin/orgs/{slug}/audit-events/{id}Get an audit event - GET
/v1/admin/audit-catalogGet the audit event catalog - GET
/v1/admin/orgs/{slug}/threatsGet the threat overview - GET
/v1/admin/orgs/{slug}/threats/sign-insGet the shape of the refused sign-ins - GET
/v1/admin/deployment/client-ipGet how the client address is determined
About this API
- Nauthera documentation: https://www.nauthera.io/docs/v1
- Contact: Nauthera https://www.nauthera.io/imprint
- Terms of service