Skip to main content

​
Overview

The Portal API allows you to generate secure, time-limited links that give your customers access to the WorkOS Admin Portal. This enables self-service configuration of SSO, Directory Sync, Domain Verification, and other enterprise features.

​
Methods

Generates a one-time-use Admin Portal link for an organization.
​
options
object
required
Configuration for the portal link
​
response
object
Portal link response

​
Example - SSO Configuration

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

const workos = new WorkOS('sk_example_123456789');

const { link } = await workos.portal.generateLink({
  intent: GeneratePortalLinkIntent.SSO,
  organization: 'org_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
  returnUrl: 'https://yourapp.com/settings',
  successUrl: 'https://yourapp.com/settings/sso/success',
});

// Redirect the user to the portal link
console.log(link);
// https://id.workos.com/portal/launch?token=...

​
Example - Directory Sync

const { link } = await workos.portal.generateLink({
  intent: GeneratePortalLinkIntent.DSync,
  organization: 'org_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
  returnUrl: 'https://yourapp.com/settings',
});

// Send this link to your customer or redirect them to it

​
Example - Domain Verification

const { link } = await workos.portal.generateLink({
  intent: GeneratePortalLinkIntent.DomainVerification,
  organization: 'org_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
  returnUrl: 'https://yourapp.com/settings/domains',
});

​
Available Intents

Allows organizations to configure Audit Logs settings and export preferences.
Enables domain verification for email-based SSO discovery and organization membership.
Provides setup and configuration for Directory Sync integrations (Azure AD, Okta, Google Workspace, etc.).
Configures real-time log streaming to external services.
Allows organizations to set up SAML or OIDC Single Sign-On connections.
Facilitates renewal of SSO certificates before they expire.
Enables customers to use their own encryption keys for data security.

​
Best Practices

Portal links are one-time-use and expire after 5 minutes if not used. Generate a new link each time a user needs to access the portal.
Always validate that the user has permission to access the organization’s settings before generating a portal link.
Use returnUrl to redirect users back to your application after they finish or exit the portal. Use successUrl to redirect them after successful completion of a specific configuration task.

SSO

Configure SSO connections programmatically

Organizations

Manage organizations and their settings

Directory Sync

Work with Directory Sync data and connections

Audit Logs

Manage audit log events

Build docs developers (and LLMs) love

Get started for freeTalk to us