@agentskills/tenant-sdk

SDK for AgentSkills tenant iframe apps. Handles auth context, on-demand token retrieval, and authenticated fetch() transparently — tenant developers write zero auth code.

Installation

npm install @agentskills/tenant-sdk
# or
yarn add @agentskills/tenant-sdk

Quick start (vanilla JS / TS)

import { TenantSDK } from "@agentskills/tenant-sdk";

const sdk = await TenantSDK.init({ persistSession: true });

// Context available synchronously after init
const user = sdk.getUser();       // { id, username, email, is_admin }
const workspace = sdk.getWorkspace(); // { id, name, group_id }

// Authenticated API call — token injected automatically
const res = await sdk.fetch(`${sdk.getApiBase()}/api/runs`);
const data = await res.json();

Read run details (sanitized)

const details = await sdk.getRunDetails(
  "qs-dev-testing-freedom--a0efbc4d85",
  "86c7e0d1-8784-4647-a8bd-69494176d68f"
);

// Exposes only:
// - details.workspace_id     (from metadata.workspace_id)
// - details.thread_id        (from config.configurable.thread_id)
// - details.data_store       (from checkpoint.channel_values.data_store)
//
// Any https://...amazonaws.com URL inside data_store is masked.

React

import { TenantProvider, useTenantFetch } from "@agentskills/tenant-sdk/react";

function App() {
  return (
    <TenantProvider persistSession fallback={<div>Loading...</div>}>
      <Dashboard />
    </TenantProvider>
  );
}

function Dashboard() {
  const { fetch, user, workspace, isReady } = useTenantFetch();

  // fetch() is authenticated — no token handling needed
}

Development (without the parent shell)

Create .env.local in your project:

VITE_TENANT_SDK_MODE=dev
VITE_TENANT_DEV_TOKEN=<your personal token from the admin UI>
VITE_TENANT_API_BASE=http://localhost:8000
VITE_TENANT_DEV_USER={"id":"...","username":"dev","email":"[email protected]","is_admin":false}
VITE_TENANT_DEV_WORKSPACE={"id":"...","name":"My Workspace","group_id":"..."}

Run your app normally (npm run dev). The SDK detects it is not inside an iframe and uses these values directly — no parent shell required.

How to get a dev token: Log into the admin UI, open DevTools → Application → LocalStorage → copy the value of auth_token.

How it works

1. When mounted as an iframe, the SDK sends AGENTSKILLS_TENANT_READY to the parent shell.
2. The shell responds with AGENTSKILLS_CONTEXT_INIT containing user, workspace, and theme.
3. On sdk.fetch(), the SDK sends AGENTSKILLS_REQUEST_TOKEN to the parent.
4. The parent generates a 15-minute scoped JWT from the backend and sends AGENTSKILLS_TOKEN_RESPONSE.
5. The SDK caches the token in memory and uses it for the request. The parent is re-contacted only when the token nears expiry.