Swagger UI can use a Backend for Frontend (BFF) session cookie for interactive API calls—without putting a downstream bearer token in the browser. Serve the UI and its OpenAPI document through the BFF, point the document’s API routes at BFF proxy endpoints, and have the browser send its session cookie with requests. The BFF then authorizes the user and obtains and forwards any required downstream access token.
How Swagger UI fits into a BFF architecture
A BFF is a server layer between a frontend and backend services. It can handle frontend-specific requirements, authorize access to private APIs, aggregate responses, and transform them for the client. In this arrangement, Swagger UI is another frontend served through that layer—not a special client that needs direct access to backend credentials.
The browser holds the BFF session cookie, while the BFF keeps access and refresh tokens on the server. When a user selects “Try it out,” Swagger UI calls a BFF route. The BFF validates the session, applies authorization, obtains the appropriate downstream token, and calls the remote API. The browser does not need to know that token.
How to configure Swagger UI to use the BFF session
1. Serve the OpenAPI document through a BFF route
Publish the OpenAPI document at a BFF-controlled route and configure Swagger UI to load that route. Swagger UI can be configured with a JavaScript configuration object, a configUrl, or URL query parameters. For example, a deployment might use a route such as /bff/openapi.json; choose a path that fits your application rather than exposing a document hosted only on the downstream API.
#1 Best Overall
Protect the document route with the BFF’s authentication and authorization middleware when the API description itself should only be available to signed-in or authorized users. Make sure the document describes BFF proxy routes as its servers and paths. If it instead points “Try it out” directly at a private API origin, the calls bypass the BFF and cannot rely on the BFF session in the intended way.
2. Make interactive calls include the session cookie
Configure Swagger UI’s requests to include browser credentials. In Swagger UI’s JavaScript configuration, the relevant option is withCredentials: true. The browser can then send the BFF’s session cookie when the request targets an origin where that cookie is applicable. Do not configure an access token as a Swagger bearer token, put tokens in URL parameters, or persist downstream tokens in browser storage.
Keep the UI, OpenAPI document, and BFF API routes on the same origin when practical. This avoids much of the cross-origin configuration burden and makes cookie behavior easier to reason about. A cookie being present in the browser does not mean it will be sent to every host: its domain, path, Secure, and SameSite attributes still govern where it applies.
3. Add the BFF’s CSRF header to protected calls
Cookie-authenticated API routes need protection against cross-site request forgery (CSRF), because browsers attach eligible cookies automatically. Duende documents a pattern that requires a custom X-CSRF: 1 header on protected API requests. Configure Swagger UI’s outgoing request mechanism to add that header where the BFF requires it. For example, a JavaScript requestInterceptor can add the header to calls going to your protected BFF API routes; scope it to those routes rather than adding it indiscriminately to unrelated hosts.
The custom header is part of the defense, not a replacement for the BFF’s authentication and authorization checks. In cross-origin deployments, sending it causes a CORS preflight, so the BFF must allow the relevant origin, credentials, and header. Ensure the configured API routes and the BFF enforce the same CSRF policy; an interactive client that omits the required header should fail rather than silently bypass the protection.
4. Proxy remote APIs through the BFF
Map the API operations used by Swagger UI to BFF routes. Those routes perform the server-side work of obtaining and forwarding the appropriate downstream access token. This keeps authorization and routing in the layer designed to hold those credentials. YARP can support more advanced proxying needs, but the essential rule does not change: “Try it out” should call the BFF, not expose a downstream token to the page.
Rank #4
Same-origin and split-host deployments
A same-origin deployment—such as serving Swagger UI and its BFF API routes from the same scheme, host, and port—is operationally simpler. The browser can make credentialed requests without configuring a separate cross-origin trust relationship, while cookie scope and the request path remain easier to inspect.
If development or deployment puts the UI on a different origin from the BFF, explicitly configure credentialed CORS for the UI origin, allow the required custom header, and select cookie settings compatible with the intended cross-site request. Cross-origin credentialed requests cannot use a wildcard origin. Verify the cookie’s Secure and SameSite behavior in the actual browser and environment; changing those attributes to make a request work can have security consequences.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Best Value
Test the full login flow as well as the API call. Authentication middleware may redirect an unauthenticated browser navigation to a login page, but a fetch for an OpenAPI document or a “Try it out” request may handle that redirect differently than expected. Confirm that Swagger UI receives the OpenAPI document as JSON after login and that an authenticated operation reaches the BFF with the session cookie and CSRF header.
Quick Recap
Direct-to-API Swagger UI versus BFF-native Swagger UI
| Concern | Swagger UI calls the API directly | Swagger UI calls through the BFF |
|---|---|---|
| Token handling | A direct bearer-token flow can put the bearer token in the browser. | Downstream access and refresh tokens remain server-side; the browser carries the BFF session cookie. |
| Request path | Browser to API origin. | Browser to BFF route, then BFF to API. |
| CSRF considerations | Bearer-header authentication does not use the BFF’s cookie-based request path; other API security requirements still apply. | Cookie-authenticated routes need CSRF protection, such as the required custom header pattern. |
| Origin and CORS | Depends on where the UI and API are hosted and the API’s CORS policy. | Same-origin hosting is simpler; split-host setups need credentialed CORS and compatible cookie settings. |
| Operational scope | Can be simpler when a direct API client and its token flow are appropriate. | Centralizes authorization, routing, and downstream token handling in the BFF. |
Implementation checks and common failure modes
- OpenAPI loads, but “Try it out” fails: Inspect the document’s server URL and operation paths. They should resolve to BFF proxy routes, not an unreachable private API origin.
- The BFF sees an anonymous request: Check that Swagger UI sends credentials and that the cookie’s domain, path, Secure, and SameSite attributes permit the request. For split hosts, also verify credentialed CORS.
- Calls fail CSRF validation: Confirm that Swagger UI adds the exact required
X-CSRF: 1header to protected API calls and that the BFF accepts it under the configured CORS policy. - The API returns a login page or HTML instead of JSON: Check the authentication redirect behavior for the OpenAPI fetch and API calls. The document endpoint must return the OpenAPI document to an authenticated request, not a login page interpreted as a specification.
- A token appears in browser tools or configuration: Remove the downstream bearer-token flow from Swagger UI. The BFF should obtain and forward that token on the server.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
