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

# Configuration

Configure the Platform SDK client with API keys, workspace ID, and optional base URL overrides.

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 Concurrence dashboard                                                                                                               |
| `workspaceId`     | `string`         | ✅        | Default workspace ID injected into routes that require workspace context                                                                             |
| `baseUrl`         | `string`         | ❌        | Platform origin. Defaults to `https://platform.api-us.concurrence.com` from 0.113.1; set it for another region, staging, or a proxy                  |
| `identityBaseUrl` | `string`         | ❌        | Identity origin for `client.tokens`. Defaults to `baseUrl` when that is set, otherwise `https://identity.api-us.concurrence.com` (0.113.1 and later) |
| `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',
  baseUrl: 'https://platform.api-us.concurrence.com',
})
```

### With a Custom Base URL

Use `baseUrl` to select the host for your deployment or to route requests through a proxy. The default is `https://platform.api-us.concurrence.com` in 0.113.1 and later; on an older package, upgrade or set `baseUrl` explicitly:

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

### Identity and Agent Connections

`client.tokens.*` sends `POST /token` to the identity host, not the Platform host. From 0.113.1 the client resolves that host as `identityBaseUrl`, then `baseUrl`, then `https://identity.api-us.concurrence.com`. A client that sets `baseUrl` to a Platform host must therefore also set `identityBaseUrl`, because the Platform host does not serve `/token`. A BFF proxy that forwards `/token` can leave `identityBaseUrl` unset.

```typescript
const client = new AmigoClient({
  apiKey: process.env.AMIGO_API_KEY!,
  workspaceId: process.env.AMIGO_WORKSPACE_ID!,
  baseUrl: 'https://platform.api-eu.concurrence.com',
  identityBaseUrl: 'https://identity.api-eu.concurrence.com',
})
```

On a package before 0.113.1, `client.tokens.*` uses `baseUrl`; create a separate client whose `baseUrl` is the identity host and use it only for token helpers. For `loginWithDeviceCode()`, pass `identityBaseUrl: 'https://identity.api-us.concurrence.com'` and the target `workspaceId` explicitly. See [Identity Endpoints](/developer-guide/platform-api/platform-api/authentication.md#identity-endpoints).

Use service-returned connection URLs where available. Set `agentBaseUrl: 'wss://agent-engine.api-us.concurrence.com'` when using an agent-engine connection helper; this option does not move the workspace `/v1/{workspace_id}/sessions/connect` socket away from the Platform host. A hostname change does not enable a legacy or unsupported socket route.

## 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!,
  baseUrl: process.env.AMIGO_BASE_URL!,
  identityBaseUrl: process.env.AMIGO_IDENTITY_URL!,
})
```

Corresponding `.env` file:

```env
AMIGO_API_KEY=your-api-key
AMIGO_WORKSPACE_ID=your-workspace-id
AMIGO_BASE_URL=https://platform.api-us.concurrence.com
AMIGO_IDENTITY_URL=https://identity.api-us.concurrence.com
```

### 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
AMIGO_BASE_URL=https://platform.api-staging.concurrence.com
AMIGO_IDENTITY_URL=https://identity.api-staging.concurrence.com
```

{% endtab %}

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

```env
AMIGO_API_KEY=prod_api_key
AMIGO_WORKSPACE_ID=prod_workspace_id
AMIGO_BASE_URL=https://platform.api-us.concurrence.com
AMIGO_IDENTITY_URL=https://identity.api-us.concurrence.com
```

{% endtab %}
{% endtabs %}

## Getting Your Credentials

### API Key

Generate an API key from Concurrence Console:

1. Log in to Concurrence 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/platform-api/platform-sdk/configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.