SDK Catalog and Quickstart

How to use the portal SDK catalog, choose the right integration mode, and verify the end-to-end Mirror path

The Portal SDK download surface (Develop → SDK, /sdk/download) is the curated operator and developer entry point for the active platform contract.

Use it when you need to:

create a service credential
download a self-contained SDK handoff bundle
decide between gateway proxy, encrypted SDK, and agent / MCP modes
copy install commands or download native bundles
verify metrics, traces, usage, and product-specific runtime calls

Portal surfaces that matter

Develop -> SDK: entitlement-aware package catalog and bundle download
Service Credentials: create, rotate, and download SDK handoff bundles
Local SDK License: refresh the signed license used by native/local SDK operations
Use Mirror -> Onboarding: guided SDK setup, env blocks, and starter examples
Use Mirror -> Playground: first hosted request against the current service credential
Use Mirror -> Builder: composed protected workflow across products
Key Management: customer-generated prompt, vector, signing, CEK, and FHE rails

The supported onboarding modes

Portal Bundle Mode

An admin creates or rotates a service credential in Portal and downloads the SDK bundle while the secret is visible.

Headless MAPI Mode

Automation calls MAPI to create credentials, refresh licenses, and download non-secret bundle updates.

Gateway Proxy Mode

Swap the base URL to the gateway, send a bearer token, and get auth, telemetry, traces, policy, provider control, and optional tool routing.

Coding Agent Proxy Mode

Run Codex, Claude Code, Cursor-style agents, Pi, Aider, Cline, Continue, or other local tools through the SDK-owned localhost proxy.

Encrypted SDK Mode

Use the TypeScript, Python, or WASM SDKs for native crypto, CEK/KMS, FHE, vector, prompt, metadata, and policy flows.

Agent / MCP Mode

Use the same service credential for connectors, delegated tool paths, memory / VDB, and MCP-backed agent workflows.

Canonical runtime contract

Create a service credential in Portal.
Reveal client_id and client_secret once.
Download the service credential handoff bundle during create or rotate if you need the secret locally.
Download SDK packages separately from Develop → SDK when you need wheels, tarballs, or native bundles to install.
Exchange the credential values at the Keycloak token endpoint, or let the SDK do it from MIRROR_SERVICE_CREDENTIAL_FILE.
Confirm the enterprise owns the right products in Account Settings or Billing & Usage.
Open Key Management when you need customer-generated prompt, vector, signing, CEK, or FHE rails.
Call MAPI or Gateway with Authorization: Bearer <token>.
Use the offline signed license from the credential handoff bundle for local/native SDK operations.

Service credentials are the common runtime identity across Gateway, Assurance, Agent Security, Code Security, native crypto flows, and connector / MCP paths. They are not the same thing as customer-owned encryption keys. Use Key Management for local key generation and KMS handoff.

Service credential handoff bundle

Download this from Develop → Credentials during service-credential create or rotate, while the secret is visible. It is the local auth and license handoff for hosted and native SDK work — not the SDK package download itself.

File	Purpose
`service-credential.json`	API base URLs, token URL, tenant metadata, service credential id, and first-display secret only on create/rotate bundles
`mirror-license.json`	signed offline license for local/native SDK operations
`mirror-license-public-key.b64`	public verification key for license validation
optional key bundle	customer-generated keys when `--generate-keys` or Portal Key Management export is used

Existing credential downloads should not reveal client_secret. Use create or rotate when a new local secret handoff is required.

SDK package download

Download SDK wheels, tarballs, and native bundles from Develop → SDK (/sdk/download). The portal composes an entitlement-filtered zip from the live SDK catalog — for example Python wheels, TypeScript tarballs, WASM bundles, integration packages, and optional native bundles.

That download is separate from the service credential handoff bundle above. Typical local setup uses both:

install SDK packages from Develop → SDK
place service-credential.json and optional license files from Develop → Credentials under .secrets/

Write the credential handoff to local secrets

Use the same local layout across Gateway, VectaX, DiscoveR, AgentIQ, Code Prism, Memory, and VDB examples:

SDK_BUNDLE_DIR="/path/to/downloaded-credential-bundle"
 
mkdir -p .secrets
chmod 700 .secrets
 
# Copy or unzip the service credential handoff bundle into .secrets.
# Hosted SDK calls require a create/rotate bundle where client_secret is present.
cp "$SDK_BUNDLE_DIR/service-credential.json" .secrets/service-credential.json
chmod 600 .secrets/service-credential.json
 
# Optional: only when the bundle includes offline/local runtime license files.
if [ -f "$SDK_BUNDLE_DIR/mirror-license.json" ]; then
  cp "$SDK_BUNDLE_DIR/mirror-license.json" .secrets/mirror-license.json
  chmod 600 .secrets/mirror-license.json
fi
 
if [ -f "$SDK_BUNDLE_DIR/mirror-license-public-key.b64" ]; then
  cp "$SDK_BUNDLE_DIR/mirror-license-public-key.b64" .secrets/mirror-license-public-key.b64
  chmod 600 .secrets/mirror-license-public-key.b64
fi
 
export MIRROR_SERVICE_CREDENTIAL_FILE=.secrets/service-credential.json

Do not commit .secrets/ or paste the service credential JSON into tickets, examples, or prompts.

CLI verification path

Run these after installing the SDK and writing the bundle to .secrets/:

export MIRROR_SERVICE_CREDENTIAL_FILE=.secrets/service-credential.json
 
mirror diagnose
mirror licenses verify
mirror gateway models
mirror chat "ping"
mirror kms summary

For a new automation-owned credential:

mirror credentials create-bundle \
  --name customer-app \
  --out .secrets \
  --generate-keys

What the catalog exposes

The active SDK catalog groups packages and bundles into these surfaces:

@mirror/sdk — canonical TypeScript SDK
mirror-sdk — external Python facade aligned to the canonical contract
mirror-enc — canonical Python native bindings
mirror-engine-client — strict-FHE request builder and decrypt helper for protected inference lanes
@mirror/wasm — compiled browser / WASM helper surface
@mirror/fhe-client — TypeScript strict-FHE request builder, bundled WASM, tokenizer assets, and decrypt helper
mirror agent-proxy start — local OpenAI/Anthropic-compatible proxy for coding agents
mirror-claw-sdk, @mirror/claw-sdk, @mirror/claw-sdk-wasm, and Rust mirror-claw-sdk — Claw/OpenClaw integration packages
@mirror/anthropic-compat, @mirror/openai-agents, and @mirror/claude-agent — agent framework compatibility packages shipped in the SDK release bundle
curated native Python bundles per OS / Python version when portal download is enabled

Portal SDK downloads include the platform-specific mirror-engine-client wheel for Python protected/FHE calls and the @mirror/fhe-client tarball for TypeScript protected/FHE calls. A tester should not need to fetch the FHE client bundle from Azure DevOps separately when installing from the current Portal catalog.

Product coverage

Product / surface	Best starting mode
Gateway / VectaX runtime	Gateway Proxy Mode
Coding agents	Coding Agent Proxy Mode
Claw / OpenClaw	Coding Agent Proxy Mode plus Claw SDK package
Native crypto / PRE / vector / FPE / metadata	Encrypted SDK Mode
CEK / KMS	Encrypted SDK Mode
FHE	Encrypted SDK Mode
Memory / VDB	Proxy Mode or Agent / MCP Mode through Gateway-hosted SDK methods
Assurance	Proxy Mode or language SDK client
Agent Security	Proxy Mode or language SDK client
Code Security	Service credential + bearer token, then product-specific client or extension workflow
Connectors / MCP	Agent / MCP Mode

Quick examples

Use the exact internal acquisition command shown on Portal Develop → SDK, then install or run the package locally. Example runtime usage:

import { Mirror } from '@mirror/sdk';
 
// new Mirror() reads the service credential issued from Portal; SDK artifacts come from Develop → SDK or Service Credentials.
// from MIRROR_SERVICE_CREDENTIAL_FILE; that credential id scopes every hosted call
// to the tenant + entitlements minted in the portal.
const client = new Mirror();
 
const response = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'ping' }],
});
console.log(response.text);
 
const hits = await client.vdb.search('demo-docs', {
  vector: [0.1, 0.2, 0.3],
  topK: 3,
});

Verify the path in portal

After you send traffic:

open Gateway Metrics
open Gateway Traces
confirm usage is attributed to the service credential and project
confirm policy / telemetry signals show up as expected