JWT Expiration vs. Embedded Refresh Token: Which Approach Yields Clearer Error Handling?

Short answer

Option A — the standard JWT verifier plus a dedicated OAuth2 refresh endpoint — yields clearer 401 responses when access tokens expire. Option B, embedding a refresh token as a claim, makes error handling depend on provider ordering and exposes the refresh secret.

1. Provider ordering and status codes

Ktor evaluates authentication providers in the order they appear in the authenticate block. Each failed provider triggers onAuthenticationFailed, and the pipeline then tries the next provider. If a later provider succeeds (e.g., a refresh‑capable provider), the request succeeds and returns 200. If no provider succeeds, the final status is 401. Thus provider ordering directly determines whether the client receives a refreshed token or an error.

2. Security trade‑offs

Embedding a refresh token as a claim keeps the flow self‑contained but:

• Exposes the refresh credential to anyone who can read the access token.
• Prevents independent revocation without server‑side state.
• Requires replay protection and a maximum refresh count, increasing complexity.
• Increases token size.

A dedicated OAuth2 refresh endpoint isolates the refresh secret, supports revocation, rate‑limiting, and audit logging, at the cost of an extra round‑trip.

3. Simulating expiry with TestEngine

Use Ktor’s TestEngine to create a JWT signed with the same key and algorithm as your application, but with an exp claim set to a past timestamp. Register two authentication providers: a strict JWT provider and a second provider that checks the embedded refresh claim and issues a new access token if the original has expired. Send a request with the expired JWT and assert the response status and body depending on provider ordering.

testApplication {
    val expired = JWT.create()
        .withAudience("my-audience")
        .withExpiresAt(Instant.now().minusSeconds(60))
        .sign(Algorithm.HMAC256("secret"))

    // Provider 1: strict JWT
    // Provider 2: refresh‑claim provider

    val response = client.get("/protected") {
        header(HttpHeaders.Authorization, "Bearer $expired")
    }
    assertEquals(HttpStatusCode.Unauthorized, response.status)
}

Recommendation

Choose Option A: strict JWT provider + dedicated refresh endpoint. It provides predictable 401 semantics and keeps the refresh secret isolated. Reserve Option B for environments where an extra endpoint is impossible, but be sure to place the strict provider first and test ordering explicitly.