The Widgets API is called from the browser with a short-lived Widget token, so the security of your integration depends on both the token model and the pages that hold the token. This guide covers what your application should do to keep that token – and the data it can reach – out of an attacker’s hands.
The browser’s security headers are the last line of defense for the Widget token if an attacker manages to inject content into your page. This section recommends a Content Security Policy (CSP) and cross-origin isolation headers that work with the Widgets API, and points out the settings that break it.
These headers are set by your application on the pages it serves. They are separate from the allowed web origins you register in the WorkOS Dashboard, which control which origins the Widgets API accepts requests from.
Start from a restrictive policy and add only what your page needs.
Directive by directive:
connect-srcmust include the host that serves the Widgets API. Usehttps://api.workos.com, or your custom Authentication API domain if you have configured one. This is the only directive the Widgets API itself requires.img-srcshould also include the origins of any images you render from API responses, such asprofilePictureUrlon users or the logo paths onbranding. User pictures point wherever the user’s identity provider hosts them, so list the origins you expect, or usehttps:if they can come from anywhere.script-srcshould be'self'plus a nonce or hash for any inline scripts your framework emits.'self'trusts everything on your origin, so if users can upload files, serve them from a separate origin.style-srcshould be'self'plus a nonce or hash for any inline<style>elements. Those do not cover inlinestyleattributes, which need'unsafe-hashes'or'unsafe-inline'.'unsafe-inline'cannot run script, but it does let injected CSS leak page content, so only add it if your styling approach needs it.- The Widgets API does not load any remote scripts or styles, so no WorkOS origin belongs in either directive.
form-action 'self'stops injected markup from submitting page contents to another origin.default-srcdoes not cover form submissions, so set this explicitly.frame-ancestors 'none'prevents your page from being embedded in another site’s frame, which removes a class of clickjacking attacks against pages that hold a Widget token. Use'self'if you frame your own pages.
Content-Security-Policy-Report-Only first and watch the browser console or your report-to endpoint for violations before switching to the enforcing header.
Set Cross-Origin-Opener-Policy: same-origin-allow-popups.
This puts your page in its own browsing context group, so a cross-origin page that opens yours cannot hold a reference to your window, while still letting popups your page opens communicate back to it.
Do not use same-origin on pages that open a popup and expect it to report back through window.opener or postMessage. The data provider authorization flow is the main case: createDataProviderAuthorization returns a URL on the WorkOS API host (https://api.workos.com, or your custom Authentication API domain when the provider uses your own credentials) that you open in a popup, and same-origin severs the opener relationship with that popup. If you instead poll dataProviderAuthorizationStatus with the returned state and never rely on the popup reaching your page, same-origin is safe.
You do not need a Cross-Origin-Embedder-Policy to use the Widgets API. Only set it if your page needs cross-origin isolation for SharedArrayBuffer or high-resolution timers.
If you do need it, prefer credentialless over require-corp.
require-corp blocks every cross-origin subresource that is not served with a Cross-Origin-Resource-Policy header, which includes most provider logos and user profile pictures. credentialless loads them without credentials instead, which is fine for public images. Widgets API calls are unaffected either way: they are CORS requests authorized by a bearer token, not credentialed requests.
Note that credentialless requires Cross-Origin-Opener-Policy: same-origin to actually enable cross-origin isolation, which conflicts with the popup guidance above. If your page needs both cross-origin isolation and the data provider authorization popup, run the authorization from a page that is not isolated.
These are not specific to the Widgets API, but every page that handles a Widget token should also send them:
Strict-Transport-Security: max-age=31536000; includeSubDomainsso the token is never sent over plaintext HTTP.Referrer-Policy: strict-origin-when-cross-origin(orno-referrer) so page URLs are not leaked to third parties.X-Content-Type-Options: nosniffto stop the browser from executing incorrectly typed responses as scripts.
Headers limit what an attacker can do after an injection; the token model limits what they can take. Widget tokens are short-lived, scoped to one user and one organization, and carry only the permissions of that user’s role. Keep them in memory rather than localStorage, request them from your backend when your page loads, and never send your WorkOS API key to the browser. See Authentication for details.