Integrate with the API

Configure your app’s default return URI in the production environment. A button in the Admin Portal uses this value to allow users to return to your app unless otherwise specified when generating the Admin Portal link.

Additionally, configure success URIs to redirect users upon successfully setting up Single Sign-On, Directory Sync, or Log Streams.

Configure these links in the dashboard.

WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.

npm install @workos-inc/node

Provide the API key and, in some cases, the client ID. Store these values as managed secrets and pass them to the SDKs either as environment variables or directly in your app’s configuration.

WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

Each Admin Portal session is scoped to a specific organization resource, meaning a session can only manage connections belonging to its associated organization. Organizations may only have one connection.

For every customer that needs Admin Portal access, create an organization and maintain a reference to its ID.

import type { NextApiRequest, NextApiResponse } from 'next';
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);
const clientId = process.env.WORKOS_CLIENT_ID;

export default async (req: NextApiRequest, res: NextApiResponse) => {
  if (req.method === 'POST') {
    const organizationName = 'Example Organization';
    const organizationDomains = [
      {
        domain: 'foo-corp.com',
        state: 'pending',
      },
    ];

    const organization = await workos.organizations.createOrganization({
      name: organizationName,
      domainData: organizationDomains,
    });

    // You should persist `organization.id` since it will be needed
    // to generate a Portal Link.

    // Provision additional Enterprise-tier resources.
  }
};

A Portal link is the IT admin’s gateway to accessing the Admin Portal, where they can set up and manage resources scoped to their organization. To generate a Portal link using the API, provide the organization ID and specify one of the following intents: sso, dsync, audit_logs, log_streams, domain_verification, or certificate_renewal.

Portal links expire 5 minutes after creation for security reasons. Redirect users immediately – do not email Portal links.

import type { NextApiRequest, NextApiResponse } from 'next';
import { WorkOS } from '@workos-inc/node';

export default async (_req: NextApiRequest, res: NextApiResponse) => {
  // The ID of the organization to start an Admin Portal session for
  const organizationId = 'org_123';

  const { link } = await workos.portal.generateLink({
    organization: organizationId,
    intent: 'sso',
  });

  res.redirect(link);
};

An optional return_url parameter can specify exactly where a user should be sent after finishing in the Admin Portal. If not provided, the success URL configured on the Redirects page of the dashboard is used.