Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

HTTP Endpoints

Auth-O-Tron exposes endpoints on two ports. The main application port (default 8080) handles authentication and token management. The metrics port (default 9090) exposes health checks and Prometheus metrics.

Main Application Port (8080)

GET /authenticate

Primary authentication endpoint. Validates credentials and returns a JWT.

AspectDetails
Request headersAuthorization: Basic <base64> or Authorization: Bearer <token>. Optional: X-Auth-Realm: <realm>
Success (200)Authorization: Bearer <jwt> header in response
Failure (401)WWW-Authenticate challenge header listing available schemes
NotesSupports comma-separated credentials. If multiple credentials share the same scheme, the last one is used.

Example:

curl -H "Authorization: Basic $(echo -n 'user:pass' | base64)" \
  http://localhost:8080/authenticate

GET /whoami

Returns the authenticated user’s identity as JSON. The response reflects the same identity (after provider validation and augmenter enrichment) that would be embedded in a JWT issued by /authenticate, so callers can inspect their effective identity without decoding a JWT.

AspectDetails
Request headersAuthorization: Basic <base64> or Authorization: Bearer <token>. Optional: X-Auth-Realm: <realm>
Success (200)JSON body with the authenticated user
Failure (401)WWW-Authenticate challenge header listing available schemes

Example:

curl -H "Authorization: Basic $(echo -n 'user:pass' | base64)" \
  http://localhost:8080/whoami

Response:

{
  "version": 1,
  "username": "user",
  "realm": "localrealm",
  "roles": ["admin"],
  "attributes": {},
  "scopes": {}
}

GET /token

Creates an opaque token for the authenticated user. Requires the token store to be enabled.

AspectDetails
AuthRequired
Success (200){"token": "<uuid>"}
Failure (503)Token store disabled

GET /tokens

Lists all opaque tokens belonging to the authenticated user.

AspectDetails
AuthRequired
Success (200){"tokens": [...]}
Failure (503)Token store disabled

DELETE /token/

Deletes a specific opaque token.

AspectDetails
AuthRequired
Param{token} - UUID of token to delete
Success (204)No content
Failure (503)Token store disabled

GET /providers

Returns configured authentication providers.

AspectDetails
AuthNone
Success (200){"providers": [{"name": "...", "type": "...", "realm": "..."}]}

GET /augmenters

Returns configured augmenters.

AspectDetails
AuthNone
Success (200){"augmenters": [{"name": "...", "type": "...", "realm": "..."}]}

GET /

Landing page with service info and version.

AspectDetails
AuthNone
Success (200)HTML page with service info

Both Ports (8080 and 9090)

GET /health

Health check for load balancers and monitoring.

AspectDetails
PortsBoth 8080 and 9090
Success (200)Text: OK
UseNGINX checks, K8s probes
NoteAvailable on the metrics port only when metrics.enabled: true

Metrics Port Only (9090)

GET /metrics

Prometheus metrics endpoint.

AspectDetails
Port9090 only
FormatPrometheus text
ContentAuth attempts, latency histograms

Example output:

# HELP auth_requests_total Total authentication requests
# TYPE auth_requests_total counter
auth_requests_total{result="success",realm="internal"} 42

# HELP auth_duration_seconds Authentication latency
# TYPE auth_duration_seconds histogram
auth_duration_seconds_bucket{result="success",realm="internal",le="0.1"} 35

Endpoint Summary

MethodPathPortAuthPurpose
GET/authenticate8080CredentialsMain auth, returns JWT
GET/whoami8080CredentialsAuthenticated identity as JSON
GET/token8080JWTCreate opaque token
GET/tokens8080JWTList tokens
DELETE/token/{token}8080JWTDelete token
GET/providers8080NoneList providers
GET/augmenters8080NoneList augmenters
GET/healthBothNoneHealth check
GET/metrics9090NonePrometheus metrics
GET/8080NoneService info