Can Vert.x JWT handler attempt token refresh before returning 401 for expired credentials?

Answer first

No. The built-in Vert.x JWT authentication handler cannot be configured to attempt a refresh before returning 401 for an expired access token. The handler validates the exp claim and fails authentication immediately when the token is expired. Vert.x does not provide a native refresh-token flow.

A 401 can be deferred only by wrapping the JWT handler with custom logic that intercepts an authentication failure, attempts a refresh using a stored refresh token, and then re-authenticates the request. That wrapper is application code, not a configuration option on JWTAuthHandler.

Confirmed facts

• Vert.x separates authentication from authorization. JWTAuthHandler performs authentication only.
• The built-in validator rejects tokens whose exp claim is in the past and produces an authentication failure. No grace period or refresh hook is built in.
• There is no native refresh-token rotation in the Vert.x Web security module as of the 4.x line.

Likely explanation and practical pattern

Because authentication is a handler chain, you can implement refresh-before-401 as:

1. Run JWTAuthHandler first. On success, continue to the route authorization.
2. On authentication failure due to expiry, invoke a custom handler that looks up a refresh token from a secure store, e.g. HttpOnly cookie or server session.
3. If refresh succeeds, issue a new access token, set the user context with the new principal, and then re-run the route's authorization checks. Do not reuse the old principal.
4. If refresh fails or no refresh token is present, return 401.

Least-privilege preservation during a refresh window requires re-applying authorization after refresh, because the new access token may carry different scopes or roles than the expired one. The authorization handler should run after the refresh decision, not be cached from the previous request.

Key rollover coordination

Key rollover is independent of token expiry. To avoid false expiry rejections:

• Keep the old signing key available for verification until the maximum lifetime of tokens signed with it has passed.
• Use a JWKS source with kid and serve both old and new keys during overlap.
• Synchronize key activation on the authorization server before clients receive tokens signed with the new key.

Clock skew between client and server can cause premature expiry detection. Allow a small leeway in validation only if your threat model permits it.

Assumptions: Vert.x Web 4.x, standard JWTAuth with symmetric or asymmetric keys. Verification needed for your exact version, because built-in refresh support could be added after 4.5. One diagnostic detail that changes the recommendation: where and how the refresh token is stored and presented in your setup, e.g. HttpOnly cookie vs Authorization header, because that determines whether the wrapper can safely access it before returning 401.