Embedded Admin

Use this integration only in the stated caller context. Configure credentials first; the SDK README owns the package surface.

Embedded Admin Apps

Use an embedded admin app for a workspace-specific management UI that should live inside Console, not for mandatory product capabilities. The current surface supports one binding per workspace.

import { receiveEmbeddedAdminSession } from '@01.software/sdk/embedded-admin'

// Browser only. Forward the receipt to your own backend over HTTPS.
export async function receiveSession(consoleOrigin: string) {
  const { requestId, token } = await receiveEmbeddedAdminSession({
    consoleOrigin,
  })
  return { requestId, token }
}

import { verifyEmbeddedAdminSession } from '@01.software/sdk/embedded-admin/server'

// Trusted server only; destination and consoleOrigin are pinned app configuration.
export async function verifySession(
  consoleOrigin: string,
  destination: string,
  receipt: { requestId: string; token: string },
) {
  return verifyEmbeddedAdminSession({
    channelId: receipt.requestId,
    consoleOrigin,
    destination,
    token: receipt.token,
  })
}

The iframe calls receiveEmbeddedAdminSession({ consoleOrigin }) once and forwards the returned requestId and token to its own backend. The backend calls verifyEmbeddedAdminSession({ channelId: requestId, consoleOrigin, destination, token }) before creating an app-local session. Pin both origins; never store, log, or use the assertion as Console API authorization.

Binding management is an operator control-plane action and is intentionally not exposed as a public SDK mutation facade. Workspace admins use 01 embedded-app with a user PAT. Loopback HTTP is disabled by default; only non-production fixtures may opt in with allowLoopbackHttp: true.

Omitting --allowed-roles or the management PATCH's allowedRoles field preserves the stored execution policy, including an empty or viewer-only allowlist. A new unset policy defaults to tenant-admin; only an explicit role array replaces an existing policy. Successful commands still display the stored roles. A local dry run without the role option omits that field.

The assertion carries identity and workspace context only. Use a separate server-held credential and app authorization policy for workspace data.

The verifier defaults to super-admin and tenant-admin only. To allow an editor or viewer, both the administrator-managed binding allowedRoles and the receiver's trusted server allowedRoles option must include that exact role. For example, a receiver can pass allowedRoles: ['super-admin', 'tenant-admin', 'tenant-viewer']; never take this allowlist from browser input. Only opted-in operators see the execution view; binding configuration remains administrator-only.

The receiver server must enforce each app feature's permissions from verified tenant_role and operator_id, independently of its server credential. Direct platform viewer mutation denial remains unchanged. The 60-second assertion expiry does not revoke an app-local session; the receiver owns its session expiry, authorization rechecks, and revocation.

Next Actions

• SDK
• Webhooks