> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/classic-api/sdks/sdk-configuration.md).

# 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](/developer-guide/getting-started/regions-and-endpoints.md) 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](/developer-guide/getting-started/authentication.md) 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 a secure secret manager.
* **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**](/developer-guide/classic-api/sdks/sdk-hello-world.md)**.** Hello World example.
* [**Handle errors properly**](/developer-guide/classic-api/sdks/sdk-error-handling.md)**.** Error handling patterns.
* [**Regions & Endpoints**](/developer-guide/getting-started/regions-and-endpoints.md)**.** Configure dedicated clusters.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/classic-api/sdks/sdk-configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.