Authentication Portal API

Authentication Portal API

Purpose

Use this skill for HTTP/JSON interactions with a configured authentication portal. Surrounding Caddyfile declarations belong to configuration-authentication; route mounting belongs to configuration-http-integrations. These are configuration boundaries, not prerequisites for an HTTP client task.

For user-owned profile keys, legacy PGP/RSA metadata, ownership isolation, and canonical profile identity and transformed-claim isolation, read profile public keys. For conditional login selection, authoritative AMR and profile policy preview/ replacement, read authentication flows. For password/MFA mutations and refresh/OIDC invalidation, read local identity compatibility.

For the standalone caddy-authenticator CLI, profile configuration, terminal input and private storage, use the command maintenance reference. Keep fresh login delegated to the public authclient package; the command owns cached-token scheduling and its explicit native refresh request.

Read these files when details matter:

• ../go-authcrunch/pkg/authn/handle_json_*.go for JSON handlers and response shapes.
• ../go-authcrunch/pkg/authn/handle_http_*.go for browser versus JSON behavior.
• caddyfile_authn.go and caddyfile_authn_admin_api.go for admin directives.
• ../go-authcrunch/pkg/authn/admin_api/parser/parser.go, admin_api_config.go, respond_api.go, and handle_api_private_keys.go for the admin configuration and authorization boundary (the latter three files are directly under pkg/authn).

Upstream handler paths are read-only references under the repository scope. Keep client changes and integration tests here. If an API fix belongs to go-authcrunch, describe the separate upstream work instead of editing or testing that checkout.

JSON Requests

Portal endpoints return JSON when the request includes either:

Accept: application/json
format=json

Without one of those signals, many endpoints follow browser-oriented behavior such as rendering HTML or redirecting.

Assume endpoint paths are relative to the portal base path. If the portal is served at /auth, then /login means /auth/login, /whoami means /auth/whoami, and admin endpoints are under /auth/api/server/....

Login Challenge Sequence

For the public Go client, native transport, API-key login and private credential files, use JSON/native interoperability. Authenticate performs fresh login; renewal is a separate explicit operation.

Programmatic login is challenge-based:

1. POST <base>/login with username and realm.
2. The portal returns sandbox_id, sandbox_secret, and next_challenge.
3. The client posts the same identity plus sandbox_id, current sandbox_secret, challenge_kind, and challenge_response.
4. The portal may rotate sandbox_secret and return another challenge.
5. When all checkpoints pass, access-only JSON login returns authenticated: true, access_token_name, and access_token. An enabled, participating local refresh login instead uses the transport contract below: browser tokens arrive in cookies; opted-in native clients receive JSON tokens.

Common challenge kinds are password, totp, and mfa. The public Go authclient supports password/TOTP, including combined MFA selection. It does not implement WebAuthn/U2F assertions and returns ErrUnsupportedChallenge for an assertion challenge. A separate client that supports assertions first answers challenge_kind: mfa with challenge_response: webauthn; the next challenge contains a base64-encoded WebAuthn payload. The final response must contain the signed WebAuthn result.

Do not reuse an old sandbox_secret; use the latest value returned by the portal. Sandbox sessions are temporary and separate from the final JWT session.

Portal Refresh Transports

Use the token refresh configuration for explicit participating local realms, origin, mount, cookie naming and limits. The selected go-authcrunch implements real rotation; /api/refresh_token is no longer a timestamp probe. No enabled block means access-only behavior and 404 at the refresh/session API routes.

Browser login uses the default cookie transport. Tokens arrive in HttpOnly cookies and JSON contains session/expiry metadata without bearer credentials. After login, POST {} as JSON to <base>/api/refresh_token, <base>/api/logout, or <base>/api/refresh_session with the cookie jar, exact configured HTTPS Origin, and X-Authcrunch-Refresh: 1. Disallowed fetch metadata, origins or mixed transports fail closed. Responses preserve Cache-Control: no-store. A valid refresh cookie can rotate despite an expired or malformed access token. The browser coordinator also sends the optional rotation precondition X-Authcrunch-Refresh-Session; forward it unchanged. Session lookup is browser-only and must never recover an uncertain rotation. See browser refresh through Caddy for continuation, coordination, strict request parsing, fresh-login recovery and real Chrome tests.

Native clients require body transport enabled and send refresh_transport: body at every login checkpoint. Send no Cookie, Origin or Sec-Fetch headers. Login and rotation return access_token, refresh_token, names, session ID, and expiry metadata in JSON without cookies. Subsequent POSTs use {"refresh_token":"<credential>"}. Omitting explicit native opt-in selects browser transport; enabling the feature alone does not opt clients in.

Successful rotation changes the refresh credential and access-token jti, retains the session binding and absolute deadline, and reloads current local identity attributes. Replaying an old refresh token revokes the family. Serialize rotations and avoid automatic retries when delivery is ambiguous. Invalid/revoked credentials return 401, origin/transport violations 403, admission exhaustion 503. A family's rotation-limit exhaustion revokes it and reclaims capacity.

With a refresh cookie, GET <base>/logout displays confirmation; the session API POST completes revocation and cookie deletion, including an associated OP session. Portal refresh grants are unrelated to OIDC refresh or upstream provider refresh. API-key and other unsupported login kinds remain access-only. TestCaddyTokenRefreshE2E covers these transports through verified Caddy TLS.