401 Unauthorized error after token expiry in Swagger UI

Direct answer

No. Swagger UI should not proactively clear or refresh an expired token, and it does not do so by design. The 401 you see after the token lifetime elapses is the expected server response. The correct pattern is to let the server return 401 and require the user to re-authorize via the standard OAuth2 flow. Refresh token handling must not be done in the browser.

Confirmed facts

• Swagger UI does not enforce authentication. It only adds the Authorization header you provide.
• Tokens entered in the Authorize dialog are stored in browser storage and reused for subsequent Try it out requests until the user manually clears them.
• Swagger UI has no built-in token lifetime validation, expiry parsing, or automatic refresh logic.
• The UI keeps the stale token in the Authorize dialog after a 401 and will retry with the same header on the next Try it out.

Likely explanation

The first request succeeds with a valid short-lived access token. After the token’s lifetime elapses the API correctly returns 401 Unauthorized. Swagger UI displays the response body but has no mechanism to know the token is expired, so it leaves the token in place. This is expected behavior, not a bug.

Recommended pattern for this case

1. Define securitySchemes correctly in OpenAPI. Use type oauth2 with Authorization Code with PKCE. Declare authUrl, tokenUrl and the scopes you need.
2. Declare minimal scopes per operation in the OpenAPI security requirements. Swagger UI will request only the scopes declared for that operation.
3. Instruct users to click Authorize again when a 401 is received. The Authorize dialog will redirect to the authorization server and obtain a fresh access token.
4. Optional UX guard: add a requestInterceptor that detects 401 responses and clears the in-memory auth state or prompts the user to re-authorize. Do not attempt to refresh tokens client-side.

Never store refresh tokens in browser storage. If automatic refresh is required, perform it in a secure backend proxy that Swagger UI calls, not in the UI.

Least-privilege with short-lived tokens

Scope enforcement is done by the authorization server, not Swagger UI. Limit scopes in the OpenAPI definition per operation, request only the scopes needed for that operation, and issue short-lived access tokens with those scopes. Swagger UI will send exactly the token and scopes the user authorized.

One missing diagnostic detail that changes the recommendation: what OAuth2 flow is configured in your securitySchemes, Authorization Code with PKCE or Implicit? Implicit flow cannot support secure refresh and would require a different integration approach.