Client Initialization

The ArmorIQ SDK follows a one-key, per-request-email model.

You initialize the client once per process with your API key. For every end-user interaction, you derive a per-user scope with client.for_user(email) — that is how the SDK tags policies, audit trails, and intent tokens with the caller's identity. There is no user_id or agent_id to manage in your code; the backend resolves them from the API key + email.

ArmorIQClient

from armoriq_sdk import ArmorIQClient

client = ArmorIQClient(
    api_key="ak_live_..."   # or read ARMORIQ_API_KEY from env
)

import { ArmorIQClient } from '@armoriq/sdk';

const client = new ArmorIQClient({
  apiKey: 'ak_live_...'   // or read ARMORIQ_API_KEY from env
});

Parameters

Parameter	Type	Required	Default	Description
api_key	str	Yes	`ARMORIQ_API_KEY` env var	Your API key — must start with `ak_live_`, `ak_test_`, or `ak_claw_`
iap_endpoint	str	No	resolved from env	CSRG/IAP service URL
proxy_endpoint	str	No	resolved from env	ArmorIQ Proxy URL
backend_endpoint	str	No	resolved from env	Control-plane backend URL
use_production	bool	No	`True`	Set `False` for local development endpoints
timeout	float	No	`30.0`	HTTP timeout in seconds
max_retries	int	No	`3`	Max retry attempts for failed requests
verify_ssl	bool	No	`True`	Verify SSL certificates
mcp_credentials	dict	No	`None`	Per-MCP auth overrides (also read from env)

Parameter	Type	Required	Default	Description
apiKey	string	Yes	`ARMORIQ_API_KEY` env var	Your API key — must start with `ak_live_`, `ak_test_`, or `ak_claw_`
iapEndpoint	string	No	resolved from env	CSRG/IAP service URL
proxyEndpoint	string	No	resolved from env	ArmorIQ Proxy URL
backendEndpoint	string	No	resolved from env	Control-plane backend URL
useProduction	boolean	No	`true`	Set `false` for local development endpoints
timeout	number	No	`30000`	HTTP timeout in milliseconds
maxRetries	number	No	`3`	Max retry attempts for failed requests
verifySsl	boolean	No	`true`	Verify SSL certificates

Returns

An ArmorIQClient instance.

Raises

ConfigurationException — missing or malformed API key

Per-user scopes

All enforcement, token minting, and audit is scoped by user email. Open a scope with for_user():

scope = client.for_user("alice@example.com")
session = scope.start_session()
session.start_plan([
    {"action": "fetch_sales", "mcp": "data-mcp"},
    {"action": "analyze",      "mcp": "analytics-mcp"},
])
decision = session.check("fetch_sales", {"quarter": "Q4"})

const scope = client.forUser('alice@example.com');
const session = scope.startSession();
session.startPlan([
  { action: 'fetch_sales', mcp: 'data-mcp' },
  { action: 'analyze',     mcp: 'analytics-mcp' },
]);
const decision = session.check('fetch_sales', { quarter: 'Q4' });

for_user(email) is cheap to call — the user context (org membership, applicable policies, approver chain) is cached per email for 5 minutes.

Loading from armoriq.yaml

If you set up the project with the armoriq CLI (armoriq init), you get an armoriq.yaml file you can load directly from Python. The CLI itself is Python-only today; TypeScript config-file loading is on the roadmap.

from armoriq_sdk import ArmorIQClient

client = ArmorIQClient.from_config("armoriq.yaml")

// Coming soon — use environment variables or explicit args for now.
const client = new ArmorIQClient({
  apiKey: process.env.ARMORIQ_API_KEY!,
});

See Configuration for the full YAML schema.

Environment variables

# Required
export ARMORIQ_API_KEY="ak_live_..."

# Optional — pick an environment
export ARMORIQ_ENV="production"    # or "staging" / "local"

# Optional — endpoint overrides
export IAP_ENDPOINT="https://iap.armoriq.ai"
export PROXY_ENDPOINT="https://proxy.armoriq.ai"
export BACKEND_ENDPOINT="https://api.armoriq.ai"

Examples

import os
from armoriq_sdk import ArmorIQClient

# Using environment variables (recommended)
client = ArmorIQClient()

# Explicit API key
client = ArmorIQClient(api_key="ak_live_" + "a" * 64)

# Local development
client = ArmorIQClient(
    api_key=os.environ["ARMORIQ_API_KEY"],
    use_production=False,
)

# Per-request: scope by user email
scope = client.for_user("alice@example.com")

import { ArmorIQClient } from '@armoriq/sdk';

// Using environment variables (recommended)
const client = new ArmorIQClient({
  apiKey: process.env.ARMORIQ_API_KEY!,
});

// Explicit API key
const client2 = new ArmorIQClient({
  apiKey: 'ak_live_' + 'a'.repeat(64),
});

// Local development
const client3 = new ArmorIQClient({
  apiKey: process.env.ARMORIQ_API_KEY!,
  useProduction: false,
});

// Per-request: scope by user email
const scope = client.forUser('alice@example.com');

Migrating from an older SDK

If you have existing code passing user_id / agent_id (or userId / agentId), remove them. The SDK no longer requires these — they are resolved per-request from the API key and the email you pass to for_user().

# before
client = ArmorIQClient(
    api_key=...,
    user_id="user_12345",
    agent_id="analytics_bot_v1",
)

# after
client = ArmorIQClient(api_key=...)
scope = client.for_user("alice@example.com")

// before
const client = new ArmorIQClient({
  apiKey: '...',
  userId: 'user_12345',
  agentId: 'analytics_bot_v1',
});

// after
const client = new ArmorIQClient({ apiKey: '...' });
const scope = client.forUser('alice@example.com');

Client Initialization

On this page