Endpoints

The Nauthera auth server exposes a standard set of OAuth2 and OIDC endpoints. All endpoints are served under the issuer URL configured in your Helm values (operator.issuerUrl).

Throughout this page, {issuer} refers to your configured issuer URL (e.g., https://auth.example.com).

#Discovery

#OpenID Connect Discovery

GET {issuer}/.well-known/openid-configuration

Returns the OpenID Provider Configuration document describing all supported endpoints, scopes, response types, and signing algorithms.

curl https://auth.example.com/.well-known/openid-configuration | jq .

Example response:

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth2/authorize",
  "token_endpoint": "https://auth.example.com/oauth2/token",
  "userinfo_endpoint": "https://auth.example.com/oauth2/userinfo",
  "revocation_endpoint": "https://auth.example.com/oauth2/revoke",
  "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
  "end_session_endpoint": "https://auth.example.com/oauth2/logout",
  "scopes_supported": ["openid", "profile", "email"],
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token",
    "client_credentials",
    "urn:ietf:params:oauth:grant-type:token-exchange"
  ],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256", "ES256"],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "private_key_jwt",
    "none"
  ],
  "code_challenge_methods_supported": ["S256", "plain"],
  "claims_supported": ["sub", "iss", "aud", "exp", "iat", "email", "name", "groups"]
}

#JSON Web Key Set (JWKS)

GET {issuer}/.well-known/jwks.json

Returns the public signing keys in JWK Set format. Resource servers use these keys to verify token signatures without contacting the auth server.

curl https://auth.example.com/.well-known/jwks.json | jq .

Keys are rotated automatically on a configurable schedule (default: 30 days). During rotation, both the old and new keys are published to ensure in-flight tokens remain verifiable. See Key Rotation for details.

#Authorization

#Authorization Endpoint

GET {issuer}/oauth2/authorize

Initiates an OAuth2 authorization code flow. Redirects the user to the Nauthera login page if not already authenticated, then to the consent screen (if configured), and finally back to the client's redirect_uri with an authorization code.

Example:

https://auth.example.com/oauth2/authorize?
  response_type=code&
  client_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&
  redirect_uri=https://my-app.example.com/callback&
  scope=openid%20profile%20email&
  state=random-state-value&
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
  code_challenge_method=S256

#Token

#Token Endpoint

POST {issuer}/oauth2/token

Exchanges an authorization code, refresh token, or client credentials for tokens. The client authenticates using the method configured in spec.tokenEndpointAuthMethod (default: client_secret_basic).

Authorization Code Exchange

curl -X POST https://auth.example.com/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://my-app.example.com/callback" \
  -d "code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

Refresh Token Exchange

curl -X POST https://auth.example.com/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN"

Client Credentials

Used by ServiceAccount resources and OidcClients with client_credentials in their grantTypes. No user context — tokens represent the service itself.

curl -X POST https://auth.example.com/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=api:read"

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "v1.MRjNHMDY0YTctZTQ2...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "scope": "openid profile email"
}

#Token Revocation

POST {issuer}/oauth2/revoke

Revokes a token per RFC 7009. Revoking a refresh token also invalidates all access tokens issued from it.

curl -X POST https://auth.example.com/oauth2/revoke \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "token=REFRESH_TOKEN" \
  -d "token_type_hint=refresh_token"

Returns 200 OK with an empty body on success. Revocation is idempotent — revoking an expired or already-revoked token returns success.

#UserInfo

#UserInfo Endpoint

GET|POST {issuer}/oauth2/userinfo

Returns claims about the authenticated user per OIDC Core Section 5.3. Requires a valid access token with the openid scope.

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://auth.example.com/oauth2/userinfo

Response:

{
  "sub": "user-uuid-here",
  "email": "alice@example.com",
  "email_verified": true,
  "name": "Alice Smith",
  "groups": ["engineering", "platform"]
}

The claims returned depend on the scopes granted and the claimMappings configured in the applicable AuthPolicy:

#Session Management

#Logout Endpoint

GET {issuer}/oauth2/logout

Initiates RP-Initiated Logout. Ends the user's session and optionally redirects to a post-logout URI.

# Browser redirect
https://auth.example.com/oauth2/logout?
  id_token_hint=eyJhbGciOiJSUzI1NiIs...&
  post_logout_redirect_uri=https://my-app.example.com/logged-out&
  state=random-state

#Token Verification

Nauthera issues self-contained JWTs. Resource servers verify tokens locally using the public keys from the JWKS endpoint — no call to the auth server is needed at request time.

Token Introspection (RFC 7662): Nauthera does not currently implement the token introspection endpoint. Since all tokens are self-contained JWTs, resource servers can verify tokens locally using the JWKS endpoint. Token introspection is planned for a future release to support opaque token formats.

#Endpoint Summary

#Related Resources

• Architecture — Token signing, key rotation, and rate limiting details.
• OidcClient — Client registration and credential provisioning.
• AuthPolicy — Scope restrictions and claim mappings.
• Login Experience — Login page and consent screen customization.