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.

start_session() returns an ArmorIQSession - the object that carries the plan, makes the enforcement decisions, and records the audit trail. Note that it defaults to mode="local", which cannot perform human approvals; see Choosing a mode.

Loading from armoriq.yaml

If you set up the project with the armoriq CLI (armoriq init), you get an armoriq.yaml file the client can load directly. Available in both SDKs: ArmorIQClient.from_config() in Python and the static ArmorIQClient.fromConfig() in TypeScript. Both expand $VAR / ${VAR} environment references while loading. The TypeScript loader lazily requires js-yaml, so add it if you use this path.

from armoriq_sdk import ArmorIQClient

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

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

// Defaults to 'armoriq.yaml' when no path is given.
const client = ArmorIQClient.fromConfig('armoriq.yaml');

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