Portal

Generate secure links to the WorkOS Admin Portal for self-service configuration

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

generateLink

Generates a one-time-use Admin Portal link for an organization.

options · object · required

Configuration for the portal link

Show properties

intent · GeneratePortalLinkIntent · required

The specific Admin Portal feature to access

Options:

• audit_logs - Audit Logs configuration
• domain_verification - Domain verification management
• dsync - Directory Sync setup
• log_streams - Log Streams configuration
• sso - Single Sign-On setup
• certificate_renewal - Certificate renewal for SSO
• bring_your_own_key - BYOK (Bring Your Own Key) configuration

organization · string · required

The ID of the organization to generate the portal link for

returnUrl · string

URL to redirect the user after they complete their portal session or click the return button

successUrl · string

URL to redirect the user after successful completion of the portal intent

response · object

Portal link response

Show properties

link · string

The secure, one-time-use URL to the Admin Portal

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

audit_logs

Allows organizations to configure Audit Logs settings and export preferences.

domain_verification

Enables domain verification for email-based SSO discovery and organization membership.

dsync

Provides setup and configuration for Directory Sync integrations (Azure AD, Okta, Google Workspace, etc.).

log_streams

Configures real-time log streaming to external services.

sso

Allows organizations to set up SAML or OIDC Single Sign-On connections.

certificate_renewal

Facilitates renewal of SSO certificates before they expire.

bring_your_own_key

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.

Related Resources

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