<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

# Security

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.

## Browser security headers

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](https://workos.com/docs/widgets/quick-start#cors-configuration) you register in the WorkOS Dashboard, which control which origins the Widgets API accepts requests from.

### Content Security Policy

Start from a restrictive policy and add only what your page needs.

```http title="Recommended Content-Security-Policy"
Content-Security-Policy:
  default-src 'self';
  connect-src 'self' https://api.workos.com;
  img-src 'self';
  style-src 'self';
  script-src 'self';
  object-src 'none';
  base-uri 'self';
  form-action 'self';
  frame-ancestors 'none';
```

Directive by directive:

- **`connect-src`** must include the host that serves the Widgets API. Use `https://api.workos.com`, or your [custom Authentication API domain](https://workos.com/docs/custom-domains/auth-api) if you have configured one. This is the only directive the Widgets API itself requires.
- **`img-src`** should also include the origins of any images you render from API responses, such as `profilePictureUrl` on users or the logo paths on `branding`. User pictures point wherever the user's identity provider hosts them, so list the origins you expect, or use `https:` if they can come from anywhere.
- **`script-src`** should 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-src`** should be `'self'` plus a nonce or hash for any inline `<style>` elements. Those do not cover inline `style` attributes, 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-src` does 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.

> Deploy a new policy with `Content-Security-Policy-Report-Only` first and watch the browser console or your `report-to` endpoint for violations before switching to the enforcing header.

### Cross-Origin-Opener-Policy

Set `Cross-Origin-Opener-Policy: same-origin-allow-popups`.

```http title="Recommended Cross-Origin-Opener-Policy"
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`](https://workos.com/docs/widgets-api/data-providers/create-data-provider-authorization) 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`](https://workos.com/docs/widgets-api/data-providers/data-provider-authorization-status) with the returned `state` and never rely on the popup reaching your page, `same-origin` is safe.

### Cross-Origin-Embedder-Policy

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`.

```http title="Cross-Origin-Embedder-Policy, if you need cross-origin isolation"
Cross-Origin-Embedder-Policy: credentialless
```

`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.

### Other headers to set

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; includeSubDomains` so the token is never sent over plaintext HTTP.
- `Referrer-Policy: strict-origin-when-cross-origin` (or `no-referrer`) so page URLs are not leaked to third parties.
- `X-Content-Type-Options: nosniff` to stop the browser from executing incorrectly typed responses as scripts.

## Keeping the token out of reach

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](https://workos.com/docs/widgets-api/authentication-tokens) for details.