OpenAPI guideUpdated Jul 23, 2026

How to protect Swagger UI with Google SSO

There are two sensible ways to do this. Put an identity-aware proxy in front of an existing Swagger UI deployment, or publish the OpenAPI file as a private read-only reference when nobody needs an interactive console.

Start free Read docs

Two patterns, chosen by how the docs are used

Identity check before documentation is returned

A clear boundary around interactive API calls

A repeatable test for allowed and denied viewers

Choose the pattern before changing the deployment

The name ‘Swagger UI’ can hide two different requirements. One team needs a running web app with Try it out, plugins, and custom routing. Another simply needs colleagues or clients to read the latest OpenAPI contract. Those should not inherit the same hosting and security design.

What viewers need	Better pattern	Why
Interactive requests or custom Swagger UI behavior	Protect the existing app with an identity-aware proxy	The application, assets, and request flow stay together
A private, read-only API reference	Publish the OpenAPI file behind Google access	There is no separate docs application to operate
Public developer onboarding	Use a developer portal	Public navigation, credentials, SDKs, and onboarding need a broader system

Put the access check in front of the content

An unlisted route, robots rule, or complicated URL is not access control. The identity decision must happen before the HTML, OpenAPI file, or rendered schemas are returned. Otherwise anyone who obtains the link can still read the contract.

Send signed-out visitors to Google authentication
Authorize the resulting identity against the intended audience
Do not expose the source YAML or JSON on a second public route
Keep static assets behind the same policy when self-hosting Swagger UI

For read-only docs, publish the spec itself

When the deliverable is a generated YAML or JSON file, the file can remain the unit owned by CI. internalpage validates it, renders a read-only reference, and keeps the destination stable when the same slug is published again.

Validate and review the exact spec that will be shared
Store the internalpage token in the CI secret store
Reuse one slug for the current approved version
Share the viewer URL, not the publishing token

Publish a private API reference

npx @internalpage/cli publish ./openapi.yaml --slug api/platform

Treat Try it out as an application security decision

An API console handles origins, browser credentials, CORS, network reachability, and the possibility of state-changing requests. If viewers must send authenticated calls, keep Swagger UI as a maintained application and design its identity and network policy deliberately.

internalpage does not provide Swagger UI Try it out, collect API keys, or proxy requests. Its OpenAPI viewer is deliberately read-only.

Match access to the real audience

Workspace access is convenient for a reference used across the company. Selected-email access is better for a client, implementation partner, or temporary review group that should not inherit broader workspace access.

Workspace policy for recurring team documentation
Selected emails for named external collaborators
Expiration for time-bounded review
Separate slugs when audiences or release stages differ

Test more than the happy path

Open the final URL while signed out, with one allowed account, and with one account that must be denied. Also check whether the raw spec or any asset URL can bypass the same access decision.

Test	Expected result
Signed-out browser	Google authentication appears before documentation content
Allowed identity	The intended API version renders
Denied identity	No document or raw spec is returned
Republish	The approved update appears at the same viewer URL

FAQ

Common questions

Does internalpage host Swagger UI?

Yes. Swagger UI is available as a read-only renderer, alongside ReDoc and Scalar. internalpage disables Try it out and does not proxy authenticated API requests.

Can I limit the page to my Google Workspace?

Yes. A page can use workspace access or a selected-email audience. Test an account outside the audience before sharing the link.

Should I remove secrets from a protected spec?

Yes. Access control is not a substitute for removing credentials, sensitive examples, and unnecessary internal server details.

When is an identity proxy a better choice?

Use an identity proxy when you already run Swagger UI as an application or need interactive API calls, custom plugins, multiple assets, or network-level policy.