Igris SDK

The Igris SDK (@igris-security/sdk) is a TypeScript client for the Igris governance gateway. It generates MCP client configurations, calls MCP tools programmatically, and provides a native OpenAI-compatible interface for the LLM gateway.

Installation

npm install @igris-security/sdk

Initialize

import { Igris } from "@igris-security/sdk";

const igris = new Igris({
  apiKey: "ig_...",  // Your Igris API key
});

The baseUrl option can also be set via the IGRIS_BASE_URL environment variable.

Never commit your API key to source control. Use environment variables:

const igris = new Igris({ apiKey: process.env.IGRIS_API_KEY! });

Get Your API Key

Log in to the Igris Dashboard
Go to Settings → API Keys
Click Generate API Key
Copy the key — it’s shown only once

MCP Connections

`igris.connectHttp(slug, options?)`

Generate an HTTP connection config for any external MCP client.

const config = igris.connectHttp("github-prod", {
  user: "alice@company.com",
  traceId: "req_abc123",
  metadata: { role: "developer", team: "engineering" },
});

// config.baseUrl  → "https://api.igrisecurity.com/v1/mcp/github-prod"
// config.apiKey   → "ig_..."
// config.headers  → { "X-Igris-Trace-Id": "ig_trace_...", "X-Igris-User": "alice@company.com", ... }

Pass the result to any MCP client:

const response = await fetch(config.baseUrl, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${config.apiKey}`,
    "Content-Type": "application/json",
    ...config.headers,
  },
  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }),
});

Return type:

interface HttpConnection {
  baseUrl: string;
  apiKey: string;
  headers: Record<string, string>;
}

Identity & Metadata

Pass user identity and freeform metadata with every MCP or LLM request. Igris uses this for policy evaluation, audit trails, and trace correlation.

How It Works

The SDK translates identity options into HTTP headers:

SDK Parameter	HTTP Header	Purpose
`user`	`X-Igris-User`	End-user identity (opaque string)
`traceId`	`X-Igris-Trace-Id`	Cross-call correlation
`metadata`	`X-Igris-Metadata`	JSON key-value pairs for policy matching

All fields are optional. If omitted, the gateway still works — just without identity-based policies or user-level audit.

Trace IDs

Trace IDs group multiple tool calls from a single user request:

const traceId = "req_abc123";

const githubConfig = igris.connectHttp("github-prod", { traceId, user: "alice" });
const slackConfig  = igris.connectHttp("slack-prod",  { traceId, user: "alice" });

Auto-generation: If you don’t pass a traceId, the SDK generates one automatically (ig_trace_ + random hex). Each connectHttp() call gets its own trace ID.

Metadata for Policies

Metadata enables attribute-based access control:

metadata: {
  role: "developer",
  team: "engineering",
  environment: "production",
  customerId: "cust_456",
}

Then write policies that match on these fields:

{
  "rules": [
    { "tool": "delete_*", "action": "deny", "conditions": { "metadata.role": "intern" } },
    { "tool": "*",        "action": "allow" }
  ]
}

Condition operators:

Operator	Example	Meaning
String (shorthand)	`"metadata.role": "intern"`	Equals “intern”
`eq`	`"metadata.role": { "eq": "intern" }`	Equals “intern”
`neq`	`"metadata.role": { "neq": "admin" }`	Not equals “admin”
`in`	`"metadata.role": { "in": ["dev", "admin"] }`	Value in list
`nin`	`"metadata.role": { "nin": ["intern"] }`	Value not in list

If a policy condition references a field that is absent from the request, the rule is skipped — not denied. Metadata limits:

Constraint	Limit
Max size	4 KB
Max nesting	3 levels
Key format	No dots in key names
Invalid JSON	Header ignored (treated as absent)

User-based policies are advisory, not security boundaries. Any holder of an API key can set any X-Igris-User value. The API key is the real trust anchor.

LLM Gateway

`igris.chat.completions.create(request)`

Send a chat completion through the Igris LLM gateway. The model field must use @slug/model syntax. Non-streaming:

const response = await igris.chat.completions.create({
  model: "@openai-prod/gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user",   content: "What is the capital of France?" },
  ],
  max_tokens: 200,
  temperature: 0.7,
});

console.log(response.choices[0].message.content);
console.log(response.usage.total_tokens);

Streaming:

const stream = await igris.chat.completions.create({
  model: "@openai-prod/gpt-4o",
  messages: [{ role: "user", content: "Write a short story" }],
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}

`igris.embeddings.create(request)`

const response = await igris.embeddings.create({
  model: "@openai-prod/text-embedding-3-small",
  input: ["Hello world", "Goodbye world"],
});

console.log(response.data[0].embedding.length); // e.g. 1536

`igris.llmProviders.list()`

Fetch all registered LLM provider slugs and metadata:

const providers = await igris.llmProviders.list();
for (const p of providers) {
  console.log(`${p.slug} → ${p.name} (${p.authStyle})`);
}

`igris.connectLlm(slug, options?)`

Build an LlmConnection for use with any OpenAI-compatible SDK client:

const conn = igris.connectLlm("openai-prod", {
  user: "alice@corp.com",
  traceId: "trace-abc123",
  metadata: { role: "developer", team: "platform" },
});

// conn.baseUrl → "https://api.igrisecurity.com/llm/openai-prod/v1"
// conn.apiKey  → your Igris API key
// conn.headers → X-Igris-User, X-Igris-Trace-Id, X-Igris-Metadata-* headers

LLM Types

`ChatMessage`

interface ChatMessage {
  role: "system" | "user" | "assistant" | "tool";
  content: string | Array<{ type: string; text?: string; [key: string]: unknown }>;
  name?: string;
  tool_call_id?: string;
  tool_calls?: unknown[];
  reasoning_content?: string;  // extended thinking output (e.g. Claude reasoning)
}

`ChatCompletionUsage`

interface ChatCompletionUsage {
  prompt_tokens: number;
  completion_tokens: number;
  total_tokens: number;
  prompt_tokens_details?: { cached_tokens?: number };
  completion_tokens_details?: { reasoning_tokens?: number };
}

`ChatCompletionResponse`

interface ChatCompletionResponse {
  id: string;
  object: "chat.completion";
  created: number;
  model: string;
  choices: ChatCompletionChoice[];
  usage: ChatCompletionUsage;
}

`ChatCompletionChunk` (streaming)

interface ChatCompletionChunk {
  id: string;
  object: "chat.completion.chunk";
  created: number;
  model: string;
  choices: Array<{
    index: number;
    delta: Partial<ChatMessage>;
    finish_reason: string | null;
  }>;
  usage?: ChatCompletionUsage;  // present on the final chunk
}

Subpath Adapters

Zero-migration integration with existing SDK clients. All adapters are exported from @igris-security/sdk/adapters/{openai,anthropic,google}.

OpenAI adapter

import OpenAI from "openai";
import { Igris } from "@igris-security/sdk";
import { withIgris } from "@igris-security/sdk/adapters/openai";

const igris = new Igris({ apiKey: "ig_..." });

const openai = withIgris(
  new OpenAI({ apiKey: "placeholder" }),
  igris,
  "openai-prod",
  { user: "alice@corp.com" },
);

// Works exactly like the native OpenAI client
await openai.chat.completions.create({ model: "gpt-4o", messages: [...] });

Anthropic adapter

import Anthropic from "@anthropic-ai/sdk";
import { withIgris } from "@igris-security/sdk/adapters/anthropic";

const anthropic = withIgris(new Anthropic({ apiKey: "placeholder" }), igris, "anthropic-prod");

await anthropic.messages.create({
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }],
});

Google adapter (stub)

Google’s SDK does not expose a unified baseURL override. The Google adapter returns the LlmConnection config for manual use.

import { withIgris } from "@igris-security/sdk/adapters/google";

const conn = withIgris(null, igris, "google-prod");
// conn.baseUrl / conn.apiKey / conn.headers — apply manually

Typed Errors

All SDK methods throw typed errors on non-2xx responses:

import {
  IgrisError,
  IgrisAuthError,
  IgrisPolicyDeniedError,
  IgrisRateLimitError,
  IgrisConflictError,
  IgrisValidationError,
} from "@igris-security/sdk";

try {
  await igris.chat.completions.create({ model: "@openai-prod/gpt-4o", messages: [...] });
} catch (err) {
  if (err instanceof IgrisPolicyDeniedError) {
    console.error("Blocked by policy:", err.message);      // HTTP 403
  } else if (err instanceof IgrisRateLimitError) {
    console.error("Rate limited:", err.message);            // HTTP 429
  } else if (err instanceof IgrisAuthError) {
    console.error("Auth error:", err.message);              // HTTP 401
  } else if (err instanceof IgrisError) {
    console.error("Gateway error:", err.message, err.response);
  }
}

Error class hierarchy:

Class	HTTP Status
`IgrisAuthError`	401
`IgrisPolicyDeniedError`	403
`IgrisConflictError`	409
`IgrisValidationError`	422
`IgrisRateLimitError`	429
`IgrisError`	any other

Environment Variables

Variable	Default	Description
`IGRIS_BASE_URL`	`https://api.igrisecurity.com`	Override gateway base URL

Tool Calls

Call MCP tools programmatically with igris.mcp.

Connections

Create and manage encrypted credential vaults.

MCP Client Config

Generate configs for Claude Desktop, Cursor, and more.

API Reference

REST API endpoints for all Igris resources.

​Igris SDK

​Installation

​Initialize

​Get Your API Key

​MCP Connections

​igris.connectHttp(slug, options?)

​Identity & Metadata

​How It Works

​Trace IDs

​Metadata for Policies

​LLM Gateway

​igris.chat.completions.create(request)

​igris.embeddings.create(request)

​igris.llmProviders.list()

​igris.connectLlm(slug, options?)

​LLM Types

​ChatMessage

​ChatCompletionUsage

​ChatCompletionResponse

​ChatCompletionChunk (streaming)

​Subpath Adapters

​OpenAI adapter

​Anthropic adapter

​Google adapter (stub)

​Typed Errors

​Environment Variables

Tool Calls

Connections

MCP Client Config

API Reference

Igris SDK

Installation

Initialize

Get Your API Key

MCP Connections

`igris.connectHttp(slug, options?)`

Identity & Metadata

How It Works

Trace IDs

Metadata for Policies

LLM Gateway

`igris.chat.completions.create(request)`

`igris.embeddings.create(request)`

`igris.llmProviders.list()`

`igris.connectLlm(slug, options?)`

LLM Types

`ChatMessage`

`ChatCompletionUsage`

`ChatCompletionResponse`

`ChatCompletionChunk` (streaming)

Subpath Adapters

OpenAI adapter

Anthropic adapter

Google adapter (stub)

Typed Errors

Environment Variables