Skip to main content
ApiGlow v0.3.0
EN
Copy page

When the browser blocks the call.

Try-it requests are plain fetch calls from the reader’s browser to your API. Nothing passes through a server of ours, because there isn’t one — which also means nothing can work around the browser’s same-origin policy. If the docs and the API live on different origins, the API must allow the docs’ origin via CORS, or the browser blocks the call before it leaves.

When a send fails, ApiGlow diagnoses it in the UI: offline, mixed content, CORS, or an unreachable host. The diagnosis is phrased as “most likely”, because the browser hides the details from the page.

Allow the docs’ origin

Answer the preflight with Access-Control-Allow-Origin naming the docs’ origin — or * for a public API without credentials — plus the methods and headers your API uses.

If the docs are served from the API’s own origin, there is no cross-origin request and nothing to configure.

Expose the headers worth reading

Without Access-Control-Expose-Headers on the API side, the browser reveals only a short safelist of response headers. Rate-limit, pagination and deprecation headers stay invisible even when the call succeeds, and ApiGlow flags that. Expose them and the network insights get their material back.

Timing-Allow-Origin does the same job for transfer facts. Without it, a cross-origin response reports sizes of zero, and the compression and cache chips do not render.

A proxy, if you host one

tryIt.proxyUrl declares a CORS proxy as a template, where {{target}} is replaced by the encoded target URL:

{ "tryIt": { "proxyUrl": "https://proxy.example.com/?url={{target}}" } }

The app ships no proxy and runs none. This is a hook for one you host and trust. When it is configured, the UI suggests it on CORS failures.

For an API authenticated by an httpOnly session cookie, the browser neither stores nor sends the cookie cross-origin by default. Set tryIt.requestCredentials: "include" and meet the three server-side requirements that come with it:

  • Access-Control-Allow-Credentials: true
  • an explicit Access-Control-Allow-Origin — * is rejected
  • a SameSite=None; Secure cookie

Note that "include" is incompatible with Access-Control-Allow-Origin: *: the browser rejects the preflight even when there is no cookie to send. In a multi-spec installation, set this on the spec entry that needs it rather than at the root.

OAuth2 adds two requirements

The in-browser flows — Authorization Code + PKCE, and client credentials — need two things from the authorization server:

  • The redirect_uri sent is the host page’s URL without its hash, and must be registered as-is.
  • The token endpoint must allow the docs’ origin in CORS, like any other try-it call.

Or avoid CORS entirely

openapi.spec carries the schema in the page and removes the schema fetch from the equation. Hosting the docs on the API’s own origin removes the rest: same origin, no preflight, and the "same-origin" default works as it is.