API Reference
OAuth2 and OpenID Connect endpoints served on the public listener.
The public-facing identity API of nauthera-server. Implements the OAuth 2.1
- OpenID Connect provider contract: discovery (OIDC Discovery 1.0 and RFC 8414 AS metadata), the JSON Web Key Set, the authorization and token endpoints (with PKCE, device, token-exchange and refresh grants), pushed authorization requests, token introspection and revocation, UserInfo, dynamic client registration + management, and RP-initiated logout.
Sender-constraining (DPoP, RFC 9449) and issuer identification (RFC 9207)
are supported per the OAuth 2.0 Security BCP (RFC 9700). Flow logic is
scaffolded in this bootstrap: not-yet-implemented flows return spec-shaped
temporarily_unavailable errors.
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 flow16 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 and set passwords for local users through the admin API. Pairs with the users.create, users.update, users.delete 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.
Client credentials flow12 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 and set passwords for local users through the admin API. Pairs with the users.create, users.update, users.delete 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.
Permissions19
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.
Endpoints
Discovery
OpenID Connect discovery, AS metadata, and key material.
OAuth2
OAuth2 protocol endpoints (RFC 6749, 7009, 7662, 8628, 8693, 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 - 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/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/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}/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}/invitationSend a user a new invitation - GET
/v1/admin/orgs/{slug}/users/{id}/devicesList a user's known browsers and networks - 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/deployment/client-ipGet how the client address is determined
About this API
- Architecture and configuration docs: https://github.com/nauthera/nauthera-server/tree/main/docs
- Contact: Nauthera Maintainers https://github.com/nauthera/nauthera-server security@nauthera.io
- License: Apache-2.0
- Terms of service