> 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/platform-api/platform-sdk/configuration.md).

# Configuration

The Platform SDK uses bearer token authentication. Each client has a default workspace ID that resource methods inject when the API route requires workspace context. Account-level and authentication routes remain unscoped.

## Configuration Parameters

| Parameter      | Type             | Required | Description                                                                                                                     |
| -------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`       | `string`         | ✅        | API key from the Amigo dashboard                                                                                                |
| `workspaceId`  | `string`         | ✅        | Default workspace ID injected into routes that require workspace context                                                        |
| `baseUrl`      | `string`         | ❌        | Override the default `https://api.platform.amigo.ai` (for example, a backend-for-frontend proxy path)                           |
| `retry`        | `RetryOptions`   | ❌        | Retry tuning: `maxAttempts` (default 3, including the first attempt), `baseDelayMs` (default 250), `maxDelayMs` (default 30000) |
| `maxRetries`   | `number`         | ❌        | Convenience alias for the number of retries after the first attempt                                                             |
| `timeout`      | `number`         | ❌        | Default request timeout in milliseconds                                                                                         |
| `headers`      | `HeadersOptions` | ❌        | Additional headers sent with every request                                                                                      |
| `hooks`        | `ClientHooks`    | ❌        | Request lifecycle hooks for logging, tracing, or metrics                                                                        |
| `fetch`        | `typeof fetch`   | ❌        | Custom fetch implementation (proxy routing, cookie forwarding, or test mocking)                                                 |
| `agentBaseUrl` | `string`         | ❌        | Base URL for agent-engine WebSocket endpoints when they are served from a different host than `baseUrl`                         |

Passing a missing or empty `apiKey` or `workspaceId` throws a `ConfigurationError` at construction time.

## Creating a Client

```typescript
import { AmigoClient } from '@amigo-ai/platform-sdk'

const client = new AmigoClient({
  apiKey: 'your-api-key',
  workspaceId: 'your-workspace-id',
})
```

### With a Custom Base URL

Use `baseUrl` to route requests through a proxy or to a non-default endpoint:

```typescript
const client = new AmigoClient({
  apiKey: 'your-api-key',
  workspaceId: 'your-workspace-id',
  baseUrl: 'https://api.platform.amigo.ai', // default
})
```

## Environment Variables

The recommended approach for production is to read credentials from environment variables rather than hardcoding them.

```typescript
import 'dotenv/config'
import { AmigoClient } from '@amigo-ai/platform-sdk'

const client = new AmigoClient({
  apiKey: process.env.AMIGO_API_KEY!,
  workspaceId: process.env.AMIGO_WORKSPACE_ID!,
})
```

Corresponding `.env` file:

```env
AMIGO_API_KEY=your-api-key
AMIGO_WORKSPACE_ID=your-workspace-id
```

### Separate Environments

Use separate `.env` files per environment:

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

```env
AMIGO_API_KEY=dev_api_key
AMIGO_WORKSPACE_ID=dev_workspace_id
```

{% endtab %}

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

```env
AMIGO_API_KEY=prod_api_key
AMIGO_WORKSPACE_ID=prod_workspace_id
```

{% endtab %}
{% endtabs %}

## Getting Your Credentials

### API Key

Generate an API key from Amigo Console:

1. Log in to Amigo Console.
2. Open **Govern > API Keys & Tokens**, then select **Workspace API Keys**.
3. Click **Create API Key** and choose the required duration from 1 to 90 days. Console defaults to 30 days.
4. Copy the key. It is only shown once.

{% hint style="warning" %}
**Never commit API keys to source control.** Use environment variables or a secrets manager.
{% endhint %}

### Workspace ID

Console URLs use the workspace slug rather than the workspace UUID:

```
https://<console-host>/<workspace-slug>/...
```

Use the workspace UUID supplied with your API credentials or returned by workspace metadata. Do not substitute the URL slug, and do not assume every resource response includes a `workspace_id` field.

## Security Best Practices

* **Rotate API keys regularly.** Every key is created with an expiration; rotate before expiry.
* **Grant the minimum permissions needed.** API keys carry a role and an explicit permission list; scope each key to what the workload actually uses.
* **One key per environment.** Use separate keys for development, staging, and production.
* **Never log credentials.** Avoid printing `apiKey` or config objects.

## Next Steps

* [**Quickstart**](/developer-guide/platform-api/platform-sdk/quickstart.md)**.** Make your first API call.
* [**Error Handling**](/developer-guide/platform-api/platform-sdk/error-handling.md)**.** Handle authentication and other errors.


---

# 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/platform-api/platform-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.