Postream

Loading the index…

Docs: Allowed domains and CORS

Allowed domains and CORS

The blog's domains unlock the publishable key in the browser and decide CORS.

Only those who call the API from the browser, with the publishable key (pk_), need this. From the blog's server, with the secret key (the recommended path), none of this applies.

Add the domains

In the panel, under Public API → Domains allowed in the browser, one per line:

blog.example.com
*.example.com
  • blog.example.com only covers that host; *.example.com covers any subdomain (not example.com itself, which needs its own line).
  • Always https, on the default port. No path or scheme.
  • localhost, 127.0.0.1 and [::1] (any port, http or https) only with Allow localhost ticked, for development.

The publishable key only works with an Origin (or Referer) on one of these domains. Outside them, or with no origin, the API answers 403 ORIGIN_NOT_ALLOWED.

Secret key in the browser

By default, a secret key that arrives with a browser Origin is refused with 403 SECRET_KEY_IN_BROWSER: anyone who opens the page would see the key. Accept the secret key from the browser turns this refusal off.

CORS

  • It only exists on the key route (/public/v1/posts…). The per-site route has no CORS: it goes to the Cloudflare cache, and the browser does not read its responses from another origin.
  • The response only carries Access-Control-Allow-Origin for the origins of the allowed domains.
  • The preflight (OPTIONS) carries no key, so it answers any origin; the GET decides.
  • Accepted headers: Authorization and If-None-Match.
  • Headers exposed to JavaScript: ETag, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After.
  • No cookies: the public API's CORS never uses credentials.
// On a page of blog.example.com
const res = await fetch("https://api.postream.blog/public/v1/posts?locale=en-US", {
  headers: { Authorization: "Bearer pk_..." },
});

The "Try it" panel in this documentation

The endpoint pages have a panel to call the API from here, with a publishable key. For it to work with your site, add this documentation's domain to the allowed domains, test, and then remove it if you want.