Widgets API: Build any WorkOS-powered UI without the back-end hop

WorkOS has long offered Widgets: prebuilt React components that drop a user management table, invitations flow, or security settings panel into your app in minutes. Widgets are good at what they do, but they set a ceiling. You get the UI we built, shaped the way we shaped it. Today we are opening up what is underneath them with a new GraphQL API that gives you the data and mutations directly, so you can build exactly the UI you want.

Why GraphQL, and why now

When we built Widgets, getting a working user management UI into an app required real effort. Today, a developer with a coding agent can scaffold that same UI in an afternoon. The bottleneck has shifted from "can I build this" to "is the API powerful enough that my agent can succeed on the first try."

GraphQL fits that world well. The schema is introspectable, so an agent can read it and write a correct query without documentation. You ask for exactly the fields you need and get back nothing extra. A page that needs user details, their role, and their recent sessions can fetch all of that in a single request rather than chaining three REST endpoints together.

There is also a DX reason. Widgets work by taking your user's session and using it to authenticate requests client-side, so your back end never has to proxy that data. The GraphQL API works the same way. You get the same session-aware, client-side access model, just without the prebuilt UI on top.

What you can build with the Widget API

The closed beta launches with full user management support. That covers the complete lifecycle of users, memberships, and invitations in your app:

• Queries: me, user(id), organization(id), organizationMemberships, roles, permissions, invitations, sessions, passkeys, mfaFactors
• Mutations: inviteUser, revokeInvitation, updateMemberRole, removeMember, updateProfile, enrollTotp, removeMfaFactor, revokeSession, changeEmail

This is enough to build a fully custom user management table, an invitations flow, a member settings page, or any other UI that today relies on Widgets.

Coming shortly after launch, we plan to expand the API surface to cover:

• SSO and Directory Sync: query connections, directory users, and groups, with mutations for creating and managing SSO connections.
• Audit logs: flexible filtering by actor, action, target, and time range.
• RBAC: full role and permission management, including effectivePermissions per user.
• Feature flags, Pipes, API keys, and Vault: starting read-only, with mutations to follow.

How it works

The API is session-aware. Your server mints a short-lived, origin-pinned token using your WorkOS API key and hands it to the browser. The browser uses that token to query the API directly. Requests are rejected if they come from an origin that is not on your allowlist, the same way redirect URIs work today.

Mint a token server-side:

  
curl -X POST https://api.workos.com/client/token \
  -H "Authorization: Bearer $WORKOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_...",
    "user_id": "user_..."
  }'
  

Then use that token to call the GraphQL endpoint from the browser:

  
curl -X POST https://api.workos.com/client/graphql \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ me { id email } }"}'
  

A fuller query for a user management table looks like this:

  
query OrgMembers($limit: Int = 10, $after: String) {
  organizationMemberships(limit: $limit, after: $after) {
    data {
      id
      email
      firstName
      lastName
      profilePictureUrl
      status
      lastActivityAt
      roles {
        slug
        name
      }
    }
    listMetadata {
      after
      before
    }
  }
}
  

What about Widgets

Widgets are not going anywhere. If you want a prebuilt user management table or invitations flow you can drop in and move on, that is still the fastest path. The GraphQL API is for teams who want to own the UI completely, add custom columns, combine WorkOS data with their own, or build surfaces Widgets do not cover, like a cross-org IT admin panel.

Over time, Widgets themselves will consume this API internally, which means improvements to the underlying data layer will benefit both paths.

Get access now

The GraphQL API is launching in closed early access. Reach out via Slack or email to get access. We are looking for teams actively building custom user management or admin surfaces who can give us detailed feedback on the schema and auth model before we open it more broadly.