Endpoints

All paths below are relative to an organization's base URL. That is the server root for the main org and /orgs/{slug} for every other org (see Organizations). Every public-listener endpoint on this page is declared in the OpenAPI document api/openapi/nauthera.yaml, except those marked as mounted by hand, and the discovery document advertises only endpoints that actually serve requests. A test drives the live server and fails the build if an advertised endpoint answers temporarily_unavailable.

#Discovery

For every org other than the main one, the discovery documents and the JWKS under /orgs/{slug}/.well-known/ are mounted by hand. Both discovery documents are also served at the RFC 8414 path-inserted locations on the server root, /.well-known/openid-configuration/orgs/{slug} and /.well-known/oauth-authorization-server/orgs/{slug}, which are mounted by hand too.

#OAuth 2.0 and OpenID Connect

Front-channel and back-channel logout are both supported and advertised (frontchannel_logout_supported, backchannel_logout_supported). Front-channel runs only when /end_session ends the session at once.

Tokens. Access tokens are JWTs with typ: at+jwt (RFC 9068), signed with ES256 or RS256. Depending on scope and flow, ID tokens and access tokens carry sub, iss, aud, exp, iat, jti, nbf, auth_time, nonce, at_hash, amr, acr, sid, scope, client_id, org, roles, email, email_verified, name and preferred_username. See Tokens & Sender Constraint.

#Dynamic client registration

#Hosted sign-in API

The hosted sign-in UI calls these JSON endpoints. They are part of the public contract, but you will rarely call them yourself.

#Admin API

The admin API lives at the server root, and the organization it acts on is named in the path. A token acts in the org whose issuer minted it, and only a token minted for one of that org's two reserved admin clients is accepted: the dashboard's {slug}-admin-console or the {slug}-admin-m2m machine client. A token from any other client is refused, whatever scopes and roles stand behind it. Every call needs an access token that carries the operation's scope, and its caller must hold the operation's permission, which the contract declares per operation (x-permission). Permissions come from the roles the caller holds in the token's org: for a user, read from the database on every call; for an org's {slug}-admin-m2m client, the roles it was provisioned with. A token can act in another org only if its caller holds a platform role in the main org. See Admin API & Users.

The user list finds users by name or email (q, match) and filters by status, locked, second_factor and creation and last sign-in dates; it sorts by created_at, email, id, last_login_at or username. The client list searches and filters by type, authentication method, grant type and source. The device list names the browsers and networks a user has signed in from. The session list covers active sessions and filters by user or client; a user's session history lists the ones that ended. The audit counts bucket events over time, grouped and filtered like the audit list. The tail returns audit records in the order they reached the store, from where the last read left off, for a SIEM or detector following the log. The mail test sends a message through the org's relay to the calling administrator's own address and reports what the relay answered. The client-IP endpoint reports where the deployment reads the client address from (security.client_ip), which trusted proxies are wider than they need to be, and whether recent traffic looks like it arrives through a proxy the configuration does not name. Date-windowed lists and counts take from and to, at most 90 days apart. Every list is cursor-paginated.

The built-in roles are org-viewer, org-auditor, user-support, manage-users, org-owner and manage-org in any org, and the platform roles platform-viewer, platform-auditor and manage-organizations, which count only in the main org, where they reach every org. manage-organizations holds every permission, platform.audit included, which platform-scoped audit records need. An operation marked recent sign-in also needs a token whose sign-in is no older than auth.admin.max_auth_age (default 15 minutes), with a second factor when mfa.required is set; an older or weaker one gets a 401 insufficient_user_authentication with an RFC 9470 step-up challenge. A token with no sign-in behind it, such as a machine client's, is refused there.

The dashboard's console client registers the session, client, insights and role scopes on top of the admin scopes. The machine clients register only the admin scopes: nauthera.users:read, nauthera.users:write and nauthera.audit:read, plus nauthera.orgs:read and nauthera.orgs:write for the main org's.

#Errors

The OAuth endpoints (/authorize, /par, /token, /device_authorization, /introspect, /revoke and /end_session) answer with the RFC 6749 error object, and /register with the RFC 7591 one. Every other endpoint, /userinfo included, answers with an RFC 9457 application/problem+json document that carries no internal detail. Its code is one of the codes the OpenAPI document lists, and its type is urn:problem-type:<code>. A problem without a code, such as a generic 500, has type: about:blank. A 401 from /userinfo also carries a WWW-Authenticate challenge. Every response carries an X-Request-ID header.

A request refused by the rate limit, or for a repeated header, gets a problem document on every endpoint, OAuth ones included. So does a request to an OAuth endpoint that cannot be read, repeats a form parameter or fails schema validation, instead of the RFC 6749 error object (#324), and a request to /register whose body cannot be read, is missing or fails schema validation, instead of the RFC 7591 one. A browser navigation can get an HTML error page instead of the JSON body, and always does when the rate limit refuses it. See Errors & Troubleshooting. OAuth responses are sent with Cache-Control: no-store.

#Public banner

GET /healthz on the public listener answers {"service":"nauthera-server","version":"…"}. It reports the build version and checks no dependency. It is mounted by hand, so it is not in the OpenAPI document. The Kubernetes probes use the admin listener.

The admin dashboard is served as static files at /admin/ for the main org and /orgs/{slug}/admin/ for every other org, also mounted by hand. Every other path that no endpoint claims is the hosted sign-in UI, except an unknown /v1/ path, which answers a 404 problem document.

#Admin listener (:9090)

#gRPC listener (:9091)

grpc.health.v1.Health and nauthera.admin.v1.AdminService. See Architecture.