Configuration

This guide covers configuring the Amigo SDK clients with the required authentication credentials and optional settings.

Configuration Parameters

Both SDKs require the following configuration parameters:

Parameter	Python SDK	TypeScript SDK	Required	Description
API Key	api_key	apiKey	✅	API key from Amigo dashboard
API Key ID	api_key_id	apiKeyId	✅	API key ID from Amigo dashboard
User ID	user_id	userId	✅	User ID on whose behalf requests are made
Organization ID	organization_id	orgId	✅	Your organization ID
Base URL	base_url	baseUrl	❌	API base URL (defaults to https://api.amigo.ai)

Creating SDK Clients

Python

The Python SDK supports both context manager and direct instantiation patterns:

Context Manager (Recommended)

from amigo_sdk import AmigoClient

# Using context manager for automatic resource cleanup
with AmigoClient(
    api_key="your-api-key",
    api_key_id="your-api-key-id",
    user_id="user-123",
    organization_id="org-456",
    base_url="https://api.amigo.ai"  # optional
) as client:
    # Use the client
    org = client.organization.get()
    print(f"Organization: {org.name}")

Direct Instantiation

from amigo_sdk import AmigoClient

# Direct instantiation - remember to handle cleanup manually
client = AmigoClient(
    api_key="your-api-key",
    api_key_id="your-api-key-id",
    user_id="user-123",
    organization_id="org-456"
)

try:
    org = client.organization.get()
    print(f"Organization: {org.name}")
finally:
    # Cleanup resources
    client.close()

TypeScript

The TypeScript SDK requires configuration to be passed during initialization:

import { AmigoClient } from "@amigo-ai/sdk";

// Initialize client with configuration
const client = new AmigoClient({
  apiKey: "your-api-key",
  apiKeyId: "your-api-key-id",
  userId: "user-123",
  orgId: "org-456",
  baseUrl: "https://api.amigo.ai", // optional
});

// Use the client
const org = await client.organizations.getOrganization();
console.log(`Organization: ${org.name}`);

Regional Base URLs

Use the base URL that matches your organization’s region:

• US: https://api.amigo.ai

• EU: https://api-eu-central-1.amigo.ai

• AU: https://api-ap-southeast-2.amigo.ai

Set this via base_url (Python) or baseUrl (TypeScript), or with AMIGO_BASE_URL.

Python

with AmigoClient(
    api_key="...",
    api_key_id="...",
    user_id="...",
    organization_id="...",
    base_url="https://api-eu-central-1.amigo.ai",  # EU
) as client:
    ...

TypeScript

const client = new AmigoClient({
  apiKey: "...",
  apiKeyId: "...",
  userId: "...",
  orgId: "...",
  baseUrl: "https://api-ap-southeast-2.amigo.ai", // AU
});

See Regions & Endpoints for full guidance and cURL examples.

Environment Variable Configuration

Python

The Python SDK can automatically load configuration from environment variables:

import os
from dotenv import load_dotenv
from amigo_sdk import AmigoClient

# Load environment variables from .env file
load_dotenv()

# Client will automatically use environment variables
# if no parameters are provided
with AmigoClient() as client:
    org = client.organization.get()
    print(f"Organization: {org.name}")

Supported environment variables for Python:

• AMIGO_API_KEY

• AMIGO_API_KEY_ID

• AMIGO_USER_ID

• AMIGO_ORGANIZATION_ID

• AMIGO_BASE_URL

TypeScript

The TypeScript SDK requires explicit configuration but can use environment variables:

import "dotenv/config";
import { AmigoClient } from "@amigo-ai/sdk";

// Must explicitly pass configuration from environment variables
const client = new AmigoClient({
  apiKey: process.env.AMIGO_API_KEY!,
  apiKeyId: process.env.AMIGO_API_KEY_ID!,
  userId: process.env.AMIGO_USER_ID!,
  orgId: process.env.AMIGO_ORGANIZATION_ID!,
  baseUrl: process.env.AMIGO_BASE_URL, // optional
});

const org = await client.organizations.getOrganization();
console.log(`Organization: ${org.name}`);

Getting Your Credentials

API Key & API Key ID

You can generate API credentials in two ways:

Option 1: Admin Dashboard

1. Log in to your service account

2. Navigate to https://<your-org-id>.amigo.ai/admin/settings

3. Click "Create API Key" and select a duration

4. Securely store both the API key and key ID

Option 2: Programmatic Generation

Use the API to create keys programmatically. See the Authentication Guide for detailed instructions.

Organization ID

Your organization ID can be found in:

• Your Amigo dashboard URL: https://<your-org-id>.amigo.ai

• Organization settings in the admin dashboard

• The response from user creation endpoints

User ID

The User ID represents the user on whose behalf API calls are made:

• Use the ID returned when creating users via the API

• Found in the user management section of the admin dashboard

• Required for user impersonation and conversation management

Configuration Best Practices

Security

• Never commit credentials: Use environment variables or secure secret management

• Rotate API keys regularly: Set expiration dates and rotate before expiry

• Use service accounts: Create dedicated service accounts for applications

• Limit permissions: API keys inherit the permissions of their creator

Environment Management

Create separate configurations for different environments:

Development (.env.dev)

AMIGO_API_KEY=dev_api_key
AMIGO_API_KEY_ID=dev_key_id
AMIGO_USER_ID=dev_user_123
AMIGO_ORGANIZATION_ID=dev_org_456
AMIGO_BASE_URL=https://dev-api.amigo.ai

Production (.env.prod)

AMIGO_API_KEY=prod_api_key
AMIGO_API_KEY_ID=prod_key_id
AMIGO_USER_ID=prod_user_123
AMIGO_ORGANIZATION_ID=prod_org_456
AMIGO_BASE_URL=https://api.amigo.ai

Configuration Validation

Both SDKs will validate configuration parameters at initialization:

Python

# Python SDK - will raise ValueError for missing required params
try:
    with AmigoClient() as client:
        pass
except ValueError as e:
    print(f"Configuration error: {e}")

TypeScript

// TypeScript SDK - TypeScript will catch missing params at compile time
const client = new AmigoClient({
  // Missing required parameters will cause TypeScript errors
  apiKey: "key",
  // apiKeyId: 'missing', // TypeScript error
  // userId: 'missing',   // TypeScript error
  // orgId: 'missing'     // TypeScript error
});

Next Steps

Once you have configured your SDK client, you're ready to:

• Create your first conversation — Hello World example

• Handle errors properly — Error handling patterns

• Regions & Endpoints — Configure dedicated clusters