@keyless-ai/sdk

AI Runtime Identity Platform — Execute any AI provider API without ever exposing raw credentials.

Why Keyless AI?

AI agents need API keys. Giving them raw keys is dangerous — keys leak into logs, context windows, and memory. Keyless AI stores credentials securely in a vault and injects them transparently at the transport layer.

❌  openai.chat({ apiKey: "sk-abc123..." })          // leaked in logs, context, memory
✅  client.callTool("global.openai.main", "chat/completions", { ... }) // alias → vault → executed safely

Installation

npm install @keyless-ai/sdk

Quick Start (MCP Gateway — Recommended)

import { createClient } from "@keyless-ai/sdk";

// One-liner: creates client + initializes session automatically
const client = await createClient({ project: "myproject" });

// Call any provider — no API key needed
const result = await client.callTool("global.openai.main", "chat/completions", {
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello!" }]
});
console.log(result.result.choices[0].message.content);

Streaming (SSE)

import { createClient } from "@keyless-ai/sdk";

const client = await createClient({ project: "myproject" });

// Stream Gemini response
const stream = client.callToolStreaming("global.gemini.main", "generateContent", {
  contents: [{ role: "user", parts: [{ text: "Tell me about AI safety." }] }]
});

for await (const chunk of stream) {
  if (chunk.type === "text") process.stdout.write(chunk.text ?? "");
  if (chunk.type === "done") break;
}

First-Time Setup

1. Go to app.keyless-ai.com/admin and enroll your project
2. Add your API credentials (OpenAI, Gemini, etc.) through the admin panel
3. Use the aliases shown in your dashboard

If your project is not enrolled, createClient() will throw:

SessionError: Project 'myproject' is not enrolled in Keyless AI
hint: Open https://app.keyless-ai.com/admin to enroll your project.

API Reference

createClient(config) — Recommended

Creates a client and initializes a session in one step.

const client = await createClient({
  project: "myproject",           // required
  url: "https://app.keyless-ai.com", // optional, default
  timeout: 30000,                 // optional, ms
});

new KeylessAI(config) / keyless(config) — Manual

For more control:

import { keyless } from "@keyless-ai/sdk";

const client = keyless({ project: "myproject" });
const session = await client.startSession();

console.log(session.available_aliases); // ["global.openai.main", "global.gemini.main", ...]

MCP Gateway Methods

| Method | Description | |--------|-------------| | startSession(opts?) | Initialize MCP session, returns available aliases | | callTool(alias, action, params?) | Execute a tool call (single response) | | callToolStreaming(alias, action, params?) | Execute with SSE streaming (AsyncGenerator) | | listTools() | List all available MCP tools |

Legacy Methods

| Method | Description | |--------|-------------| | bootstrap(opts?) | Initialize session (legacy API) | | execute(alias, payload) | Execute a credential action (legacy) | | resolve(alias) | Get masked credential info | | mintToken(opts) | Create short-lived ephemeral token | | intake(credential) | Submit new credential for onboarding |

Utility Methods

| Method | Description | |--------|-------------| | getAliases() | List available credential aliases | | hasAlias(name) | Check if a specific alias is available | | getMissingProviders() | Providers not yet configured | | getEntitlement() | Current permissions and rate limits | | can(action) | Quick permission check |

Error Handling

All errors include a code, message, and optional hint for what to do next:

import { KeylessError, SessionError, TimeoutError, NetworkError } from "@keyless-ai/sdk";

try {
  await client.callTool("global.openai.main", "chat/completions", { ... });
} catch (err) {
  if (err instanceof SessionError) {
    // Not enrolled or session expired — go to admin panel
    console.log(err.hint);
  } else if (err instanceof TimeoutError) {
    // Request took too long
  } else if (err instanceof KeylessError) {
    console.log(err.code);    // e.g. "PROVIDER_NOT_CONFIGURED"
    console.log(err.message);
    console.log(err.hint);    // Actionable next step
  }
}

Architecture

Your AI Agent
    │
    ▼
@keyless-ai/sdk
    │
    ├── startSession()  →  GET /api/start-session?project=...
    ├── callTool()      →  POST /api/tools/run
    ├── callToolStreaming() → POST /api/tools/run (SSE)
    └── listTools()     →  POST /api/mcp (JSON-RPC 2.0)
    │
    ▼
┌─────────────────────────────────────┐
│  Keyless AI Platform                │
│  app.keyless-ai.com                 │
│                                     │
│  5-layer policy pipeline:           │
│  role → session → project →         │
│  environment → credential → limit   │
└─────────────────────────────────────┘
    │
    ▼
Provider APIs (OpenAI, Gemini, Stripe, Telegram, Slack, ...)

Risk Tiers

| Tier | Access Mode | Providers | |------|-------------|-----------| | 1 — Human Only | Manual approval required | X/Twitter, Stripe, Exchange, Supabase | | 2 — AI Chrome | Browser-based acquisition | OpenAI, Gemini, Anthropic, Telegram | | 3 — AI Runtime | Fully automated | OAuth tokens, Signed URLs, Temp permits |

Requirements

• Node.js 18+
• Project enrolled at app.keyless-ai.com/admin

License

MIT — © Keyless AI