@ai-setu/admin

@ai-setu/admin

Read this first, agent. This package = control plane, not inference. Use it to manage a tenant's own workspaces, API keys, members, billing, PATs, and BYOK provider credentials. Shape mirror the OpenAI SDK ergonomic — one import, one symbol, env-var-first constructor — so if you know @ai-setu/client, you pick this up by analogy. Want chat / embeddings? Wrong package — use @ai-setu/client.

TL;DR

npm i @ai-setu/admin
export AI_SETU_PAT=tt_pat_…

import { AiSetuAdmin } from '@ai-setu/admin';
const admin = new AiSetuAdmin(); // read AI_SETU_PAT from env

const ws = await admin.workspaces.list();
const key = await admin.apiKeys.create({ workspaceId: ws[0].id, name: 'CI' });
console.log('store this once, it no come back:', key.secret);

Rules for agent

1. Auth = PAT, not workspace key. Env AI_SETU_PAT (shape tt_pat_…), or new AiSetuAdmin({ pat }). The tt_live_… key is for inference only — it no work here.
2. PAT carry a scope. admin:read = list/read only. admin:write = mutations (keys, members, billing). Wrong scope → UNAUTHORIZED.
3. Secrets show once. apiKeys.create / pats.create return the secret one time. Capture it now or lose it forever.
4. Every method take optional AbortSignal as last arg.
5. No inference here. Balance + usage live here; chat + embeddings do not.

Namespaces — the whole surface

Namespace	Methods
admin.workspaces	list, get, create, rename, delete, listMembers
admin.apiKeys	list(workspaceId), create, rotate, revoke
admin.members	invite, setRole, remove
admin.billing	creditBalance(tenantId), createTopUpIntent, topUps
admin.usage	projection(tenantId)
admin.pats	list, create, revoke
admin.providerCredentials	availability, list, upsert, test, revoke

BYOK Connections

providerCredentials.upsert creates a Connection (a slug handle) backed by a Credential (the secret), so inference bills against your upstream account, not the platform's. Pass slug — the per-request routing handle used in @<slug>/<model> model strings (label still works as a deprecated alias; slug wins). OpenAI / Anthropic carry an apiKey; AWS Bedrock carries the awsAccessKeyId / awsSecretAccessKey / awsRegion triple instead (gateway SigV4-signs your Bedrock traffic). Secrets encrypt at rest under the platform KEK, never come back — only a keyHint (last four) returns. Returned objects carry slug.

// AWS Bedrock BYOK — reached per request as model "@bedrock-prod/<model>"
const cred = await admin.providerCredentials.upsert({
  provider: 'bedrock',
  slug: 'bedrock-prod',
  awsAccessKeyId: process.env.AWS_ACCESS_KEY_ID,
  awsSecretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  awsRegion: 'us-west-2',
});

// Verify the keys authenticate (STS GetCallerIdentity — no quota burn)
const probe = await admin.providerCredentials.test(cred.id);
if (!probe.ok) throw new Error(probe.message);

// Now inference route through your AWS account:
//   client.chat.completions.create({ model: 'bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0', … })

await admin.providerCredentials.revoke(cred.id);

OpenAI / Anthropic stay key-based:

await admin.providerCredentials.upsert({
  provider: 'openai',
  slug: 'openai-prod', // reached per request as model "@openai-prod/<model>"
  apiKey: process.env.OPENAI_API_KEY,
});

Errors

import { AdminGraphQLError, AdminHttpError } from '@ai-setu/admin';

try {
  await admin.workspaces.create({ name: 'staging' });
} catch (err) {
  if (err instanceof AdminGraphQLError && err.code === 'UNAUTHORIZED') {
    // PAT lack the permission.
  } else if (err instanceof AdminHttpError && err.status === 401) {
    // PAT revoked / expired.
  }
}

Get a PAT

Mint one from the dashboard: https://app.aisetu.ai/settings/profile (Personal Access Tokens). Or have a builder agent run the OTP flow through @ai-setu/mcp. Scopes:

• admin:read — list workspaces, balance, usage
• admin:write — mutations (keys, members, billing top-ups)

Environments

Default = production (api.aisetu.ai). Point at a different control plane (e.g. a self-hosted deployment) with a full URL override:

export AI_SETU_API_BASE_URL=https://api.your-deployment.example.com

Precedence: new AiSetuAdmin({ baseUrl }) → AI_SETU_API_BASE_URL (full URL) → production.

Runtime support

• Node ≥ 20 — shared keep-alive undici.Agent, sequential calls reuse the TCP connection.
• Edge (Cloudflare Workers / Vercel) — platform fetch (already pool). undici is optional dep, edge bundlers skip it.

Under the hood (you no need this to use it)

Transport = hand-coded GraphQL strings over raw fetch. Ship <2 KB vs ~25 KB for the smallest GraphQL client, edge-safe with no polyfill. Ops live in src/operations/*.ts — easy to read or fork.

Every shipped op validate against a committed snapshot of the API's public schema (schema/schema-public.gql) in src/__tests__/schema-drift.test.ts, so a query can't silently drift from the API. graphql-codegen derive the public result types from that same snapshot — result shape can never diverge from what its query select. Refresh snapshot after an intentional API change (running ai-setu-api container needed):

pnpm --filter @ai-setu/admin schema:export
pnpm --filter @ai-setu/admin codegen   # also run automatically on build

The four AI Setu packages — which one you grab

Package	Use it when
@ai-setu/client	Runtime agent / app call inference. Drop-in for openai.
@ai-setu/admin	Scripts / CI / builder agent run control-plane ops in TypeScript.
@ai-setu/cli	Same control-plane ops from the shell.
@ai-setu/mcp	Builder agent (Claude Code, Cursor) drive onboarding + ops conversationally.

Full agent runbook = llms.txt.

License

MIT.