Developer Setup (Self-Hosted)

Connect your SDKs to a self-hosted Aira instance — API keys, base URL, webhooks, and TLS for local development.

Prerequisites

This guide assumes you have already deployed Aira self-hosted using the Self-Hosted installation guide. You should have:

A running Aira instance (e.g., https://aira.internal.yourcompany.com)
Admin access to the Aira dashboard
Python 3.10+ or Node.js 18+ on your development machine

Setting the base URL

By default, both SDKs point to the Aira cloud API (https://api.airaproof.com). To connect to your self-hosted instance, set the AIRA_BASE_URL environment variable.

# Add to your shell profile (~/.bashrc, ~/.zshrc) or .env file
export AIRA_BASE_URL="https://aira.internal.yourcompany.com"
export AIRA_API_KEY="aira_live_your_key_here"

Or pass the base URL directly when initializing the SDK:

from aira import Aira

client = Aira(
    api_key="aira_live_...",
    base_url="https://aira.internal.yourcompany.com",
)

import { Aira } from "aira-sdk";

const aira = new Aira({
  apiKey: "aira_live_...",
  baseUrl: "https://aira.internal.yourcompany.com",
});

The SDK reads AIRA_BASE_URL and AIRA_API_KEY from environment variables automatically. If both the environment variable and the constructor argument are provided, the constructor argument takes precedence.

Creating API keys

Open the Aira dashboard at https://aira.internal.yourcompany.com/dashboard.
Navigate to Settings > API Keys.
Click Create Key, give it a name (e.g., "dev-laptop"), and select the appropriate scope.
Copy the key immediately — it is only shown once.

For automated provisioning, you can create keys via the API:

curl -X POST https://aira.internal.yourcompany.com/api/v1/api-keys \
  -H "Authorization: Bearer aira_live_admin_key..." \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline", "role": "member"}'

Testing the authorize/notarize flow

Run this end-to-end test to confirm your SDK is connected and working:

from aira import Aira

client = Aira()  # reads AIRA_BASE_URL and AIRA_API_KEY from env

# Step 1: Authorize an action
action = client.authorize(
    action_type="llm_call",
    model_id="claude-sonnet-4-6",
    details={"prompt": "Summarize Q2 revenue trends"},
)
print(f"Action authorized: {action.action_uuid}, decision: {action.decision}")

# Step 2: Notarize with the model output
receipt = client.notarize(
    action_uuid=action.action_uuid,
    output="Q2 revenue grew 12% YoY driven by enterprise expansion.",
)
print(f"Receipt: {receipt.receipt_uuid}, signature valid: {receipt.valid}")

import { Aira } from "aira-sdk";

const aira = new Aira(); // reads from env

// Step 1: Authorize an action
const action = await client.authorize({
  actionType: "llm_call",
  modelId: "claude-sonnet-4-6",
  details: { prompt: "Summarize Q2 revenue trends" },
});
console.log(`Action authorized: ${action.actionUuid}, decision: ${action.decision}`);

// Step 2: Notarize with the model output
const receipt = await client.notarize({
  actionUuid: action.actionUuid,
  output: "Q2 revenue grew 12% YoY driven by enterprise expansion.",
});
console.log(`Receipt: ${receipt.receiptUuid}, signature valid: ${receipt.valid}`);

If both steps succeed and print valid IDs, your self-hosted connection is working.

Configuring webhooks for development

Your self-hosted Aira instance needs to reach your local machine to deliver webhooks during development. Use a tunnel:

# Start a tunnel to your local dev server
ngrok http 3000

# Output:
# Forwarding https://abc123.ngrok.io -> http://localhost:3000

Then register the tunnel URL as a webhook endpoint:

curl -X POST https://aira.internal.yourcompany.com/api/v1/webhooks \
  -H "Authorization: Bearer aira_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://abc123.ngrok.io/webhooks/aira",
    "events": ["action.authorized", "action.notarized", "policy.violated"]
  }'

Tunnel URLs change every time you restart ngrok (unless you have a paid plan with a stable subdomain). Remember to update your webhook URL when the tunnel restarts.

Environment variables reference

Variable	Required	Default	Description
`AIRA_BASE_URL`	Yes (self-hosted)	`https://api.airaproof.com`	Base URL of your Aira instance
`AIRA_API_KEY`	Yes	—	Your API key (starts with `aira_live_` or `aira_test_`)
`AIRA_TIMEOUT`	No	`30`	Request timeout in seconds
`AIRA_MAX_RETRIES`	No	`3`	Max retries on transient errors (429, 5xx)
`AIRA_VERIFY_TLS`	No	`true`	Set to `false` to skip TLS verification (dev only)

Add the self-signed CA to your system trust store:

# macOS
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain your-ca.crt

# Ubuntu/Debian
sudo cp your-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

Option 2: Disable TLS verification (dev only)

export AIRA_VERIFY_TLS=false

client = Aira(
    base_url="https://localhost:8443",
    verify_tls=False,  # NEVER do this in production
)

Disabling TLS verification in production is a security risk. Only use AIRA_VERIFY_TLS=false for local development with self-signed certificates.

Next steps

Performance — latency benchmarks and tuning tips
Batch Processing — patterns for high-throughput workloads
Webhook Verification — validate webhook signatures

Developer Setup (Self-Hosted)

Prerequisites

Setting the base URL

Creating API keys

Testing the authorize/notarize flow

Configuring webhooks for development

Environment variables reference

TLS certificate notes

Production self-hosted

Local development

Next steps

On this page