Embedded Admin

Use this integration only in the stated caller context. Configure credentials first; see SDK for imports and peer dependencies.

Embedded Admin AppsCopy Anchor Link

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.

The CLI example shows --allowed-roles with published CLI 0.21.0.

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.

Published SDK 0.68.0 includes the receiver's allowedRoles option; 0.65.1 does not. These CLI and SDK versions are reference releases for the examples, not first or minimum supported versions.

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.

Iframe downloads default off. Tenant admins explicitly opt in through Console or 01 embedded-app configure --allow-downloads; full configure without that flag resets false. SDK configuration normalization accepts an omitted allowDownloads and returns false. Receiver protocol version 1 is unchanged. The app owns file encryption and passwords. Host policy observation can replace or hide a frame, but does not recall downloaded files, delivered data or app sessions.

Next ActionsCopy Anchor Link

• SDK
• Webhooks