In Ktor, what does an authentication provider's challenge block control?

## When the block runs The `authenticate` route wrapper runs its named providers. If any produces a principal, the handler runs. If none does, Ktor executes the challenge of the relevant provider and the call ends there — the handler is never entered. All the failure paths converge here: - No credentials at all (no `Authorization` header, no session cookie). - Credentials present but malformed or unverifiable. - Credentials verified but your `validate` block returned null. The block receives no reason. That is a design fact worth stating in an interview, because it constrains what you can do: you cannot write "password wrong" versus "user unknown" from here, and you should not want to — that distinction is an account-enumeration oracle. Generic is correct. ## The default, and why it matters For scheme-based providers such as `basic`, the default challenge is a 401 carrying `WWW-Authenticate` with the scheme and the configured `realm`. That header is not decoration: it is the instruction that makes a browser show its native credentials dialog, and it is what an HTTP client library keys on to retry with credentials. If you override the challenge and drop the header, the dialog stops appearing — sometimes exactly what you want for a fetch-based front end, sometimes a regression you did not intend. ## Shaping it for the surface you serve **API surface.** Clients want a machine-readable body in the same envelope as every other error: `challenge { _, _ -> call.respond(HttpStatusCode.Unauthorized, ApiError("UNAUTHENTICATED", "Missing or invalid credentials")) }` Remember the body is serialized by `ContentNegotiation` like any other response, so the error type must be convertible. **Browser surface.** A session or form provider normally redirects: `challenge { call.respondRedirect("/login") }`. Carrying the originally requested path as a query parameter so the user lands where they meant to go is the usual refinement — validate it before redirecting back, since an unchecked return path is an open-redirect. **Mixed surface.** An application serving both should declare two named providers with two challenges and wrap each route subtree in the one that fits. Redirecting an XHR call to a login page produces the classic symptom of a 200 containing HTML where JSON was expected. ## Interaction with optional authentication `authenticate("auth-session", optional = true) { ... }` runs the provider but suppresses the challenge: an unauthenticated request reaches the handler with `call.principal<T>()` returning null. This is how you serve a page that shows more to a signed-in visitor without forcing a login. If you use it, every handler beneath it must treat a null principal as a normal case — an unchecked non-null assertion there turns an anonymous visit into a 500. ## What the challenge must not become The challenge answers "you are not authenticated". It is not the place for authorization failures: a caller who authenticated fine but lacks a permission should never reach it, because a principal was produced. Those must be refused by your authorization layer with 403. Conflating them tells clients to re-authenticate for a problem re-authenticating cannot fix. It is also not a logging hook by itself. Failed-authentication rate is a signal worth emitting — a spike means credential stuffing or a broken client deployment — but log it with the request metadata you already have and without the presented credentials. ## With multiple providers When `authenticate` lists several providers and all of them fail, only one challenge response is sent; the call is completed by the first provider that responds. Designing two wildly different challenges into one wrapped subtree therefore produces behaviour that depends on ordering. Prefer one mechanism per route subtree, which also keeps the client contract clear.