# 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

{% tabs %}
{% tab title="Python" %}
The Python SDK supports both context manager and direct instantiation patterns:

#### Context Manager (Recommended)

```python
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.organizations.get()
    print(f"Organization: {org.name}")
```

#### Direct Instantiation

```python
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.organizations.get()
    print(f"Organization: {org.name}")
finally:
    # Cleanup resources
    client.close()
```

{% endtab %}

{% tab title="TypeScript" %}
The TypeScript SDK requires configuration to be passed during initialization:

```typescript
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}`);
```

{% endtab %}
{% endtabs %}

## Regional Base URLs

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

* US: `https://api.amigo.ai`
* CA: `https://api-ca-central-1.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`.

{% tabs %}
{% tab title="Python" %}

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

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const client = new AmigoClient({
  apiKey: "...",
  apiKeyId: "...",
  userId: "...",
  orgId: "...",
  baseUrl: "https://api-eu-central-1.amigo.ai", // EU
});
```

{% endtab %}
{% endtabs %}

See [Regions & Endpoints](https://docs.amigo.ai/developer-guide/getting-started/regions-and-endpoints) for full guidance and cURL examples.

## Environment Variable Configuration

{% tabs %}
{% tab title="Python" %}
The Python SDK can automatically load configuration from environment variables:

```python
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.organizations.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`
  {% endtab %}

{% tab title="TypeScript" %}
The TypeScript SDK requires explicit configuration but can use environment variables:

```typescript
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}`);
```

{% endtab %}
{% endtabs %}

## 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](https://docs.amigo.ai/developer-guide/getting-started/authentication) 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:

{% tabs %}
{% tab title="Development (.env.dev)" %}

```env
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
```

{% endtab %}

{% tab title="Production (.env.prod)" %}

```env
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
```

{% endtab %}
{% endtabs %}

### Configuration Validation

Both SDKs will validate configuration parameters at initialization:

{% tabs %}
{% tab title="Python" %}

```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}")
```

{% endtab %}

{% tab title="TypeScript" %}

```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
});
```

{% endtab %}
{% endtabs %}

## Next Steps

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

* [**Create your first conversation**](https://docs.amigo.ai/developer-guide/classic-api/sdks/sdk-hello-world) - Hello World example
* [**Handle errors properly**](https://docs.amigo.ai/developer-guide/classic-api/sdks/sdk-error-handling) - Error handling patterns
* [**Regions & Endpoints**](https://docs.amigo.ai/developer-guide/getting-started/regions-and-endpoints) - Configure dedicated clusters