Authio docs

Widgets

Directory Sync widget

Drop the SCIM 2.0 provisioning surface into your product. Okta SCIM, Microsoft Entra ID, Google Workspace, JumpCloud, Rippling, and generic SCIM.

Install

pnpm add @authio/widgets react react-dom

1. Mint a widget token from your backend

const res = await fetch("https://api.authio.com/v1/widget-tokens", {
  method: "POST",
  headers: {
    authorization: `Bearer ${dashboardSessionJwt}`,
    "x-authio-tenant": tenantId,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    organization_id: "org_abc",
    scope: ["directory_sync"],
    origins: ["https://app.acme.com"],
    ttl_seconds: 1800,
  }),
});
const { token, expires_at } = await res.json();
You can mint a token with scope: ["sso_connection", "directory_sync"] if you embed both widgets on the same page — it’s the same JWT, just broader scope. The widget code path checks per-route scope, so a token without directory_sync hitting the directory widget will get a 403 widget_scope_required.

2. Embed the widget

import { AuthioDirectorySyncWidget } from "@authio/widgets";

export function DirectorySyncPage({ widgetToken }: { widgetToken: string }) {
  return (
    <AuthioDirectorySyncWidget
      token={widgetToken}
      organizationId="org_abc"
      onDirectoryUpdate={(event) => {
        if (event.type === "provisioned") {
          // The bearer token is shown ONCE. Surface it through the
          // widget's secret-reveal panel; we don't keep the plaintext
          // anywhere else.
          analytics.track("directory_provisioned", {
            id: event.directory.id,
            provider: event.directory.provider,
          });
        }
      }}
    />
  );
}

What the IT admin sees

  1. Click Provision directory — pick a provider and a display name.
  2. Authio mints a SCIM endpoint URL + a one-shot bearer token. The widget surfaces both inside a “copy this once” panel.
  3. The IT admin pastes endpoint + bearer into their IdP’s SCIM configuration (Okta / Entra / etc.).
  4. They click Sync now to verify the round-trip works. Synced users appear under the directory’s Users button.
  5. When a directory’s bearer token leaks (or every 90 days per their security review), they click Rotate token — same secret-reveal panel, new plaintext, the old one stops working immediately.

The mint / list / revoke surface for the JWT itself is documented on the Widget tokens page. The defense-in-depth story (origin enforcement, scope checks, audit emission, RLS) is on the security page.

What the widget calls

  • GET /widget/directories — list
  • POST /widget/directories — provision
  • PATCH /widget/directories/:id — update / rotate token
  • DELETE /widget/directories/:id — deprovision
  • GET /widget/directories/:id/users — paginated users
  • POST /widget/directories/:id/sync-now — trigger sync