The Widgets API does not accept your WorkOS API key. Because requests typically come from the browser, Widgets API are authorized with a short-lived Widget token that represents a single signed-in user, and – for organization-scoped operations – a single organization.
Generate a Client API token from your backend with an API key, then hand the result to the browser.
A token carries the grants your backend requested when it was issued. An operation that the token is not scoped for fails rather than returning partial data, so a request only the grants the given surface needs.
Tokens issued without an organization can still call user-scoped operations such as me and
updateProfile, but organization-scoped operations such as organizationMemberships require an organization-scoped token.
Security-sensitive operations, such as changing a password, enrolling an MFA factor, registering a passkey, or changing an email address, require the user to have recently proven who they are. When that proof is missing or stale, the operation returns a result variant telling you to re-verify before retrying.
Widget tokens are short-lived and session-bound. Treat expiry as routine; when a request fails because the token is no longer valid, request a fresh one from your backend and retry. Never ship a WorkOS API key to the browser in order to avoid this.