Skip to main content

​
Overview

The Widgets API allows you to embed WorkOS UI components directly into your application. By generating secure, scoped tokens, you can provide self-service capabilities to your users without redirecting them to external pages.

​
Methods

​
getToken

Generates a secure token for rendering WorkOS widgets in your application.
​
payload
GetTokenOptions
required
Token generation options
​
token
string
A secure JWT token to be used with WorkOS widget components

​
Example - Users Table Widget

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const token = await workos.widgets.getToken({
  organizationId: 'org_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
  userId: 'user_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
  scopes: ['widgets:users-table:manage'],
});

// Pass this token to your frontend
res.json({ widgetToken: token });

​
Example - SSO Configuration Widget

const token = await workos.widgets.getToken({
  organizationId: 'org_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
  scopes: ['widgets:sso:manage'],
});

​
Example - Multiple Scopes

const token = await workos.widgets.getToken({
  organizationId: 'org_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
  scopes: [
    'widgets:users-table:manage',
    'widgets:sso:manage',
    'widgets:domain-verification:manage',
  ],
});

​
Widget Scopes

Provides access to a user management table widget that allows viewing, inviting, and managing users within an organization.
Enables an embedded SSO configuration widget for setting up and managing Single Sign-On connections.
Allows domain verification management through an embedded widget interface.
Provides an embedded Directory Sync configuration and management interface.
Enables API key management capabilities within your application interface.

​
Frontend Integration

Once you generate a token on your backend, pass it to your frontend to initialize WorkOS widgets: 
// Example frontend integration
import { WorkOSWidget } from '@workos-inc/widget';

// Fetch token from your backend
const response = await fetch('/api/widget-token');
const { widgetToken } = await response.json();

// Initialize the widget
const widget = new WorkOSWidget({
  token: widgetToken,
  container: '#widget-container',
});

widget.render();

​
Security Considerations

Never expose your WorkOS API key to the frontend. Always generate tokens on your backend server.
Tokens are short-lived and scoped to specific organizations and permissions. Generate a new token each time a user loads a page with a widget.
The userId parameter is optional but recommended for widgets that need to associate actions with specific users, such as the users table widget.

​
Benefits of Widgets

Embedded Experience

Keep users in your application without redirects to external portals

Customizable

Widgets inherit your application’s styling and branding

Secure

Scoped tokens ensure users only access permitted resources

Maintained by WorkOS

Automatically updated with new features and security improvements

Portal

Generate links to the full Admin Portal experience

Organizations

Manage organizations programmatically

Build docs developers (and LLMs) love

Get started for freeTalk to us