> 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 helpers use their own routes and authorization boundaries. The configured workspace does not expand the credential's access.

## Configuration Parameters

| Parameter         | Type             | Required | Description                                                                                                                                                                                |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `apiKey`          | `string`         | ✅        | Workspace API key or access token accepted by the selected operation                                                                                                                       |
| `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 or a proxy                                                                  |
| `identityBaseUrl` | `string`         | ❌        | Identity origin for `client.tokens` and Identity administration resources. 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](https://docs.concurrence.com/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.

### Interactive Credentials

Use [device authorization](https://docs.concurrence.com/developer-guide/platform-api/platform-api/authentication.md#device-code-flow-cli-and-desktop-apps) for an interactive CLI or desktop application. Configure `TokenManager` with the matching regional Identity origin, and persist the returned workspace with the tokens. An organization SSO device authorization remains pinned to that workspace.

Call `signOut()` on the `TokenManager` that holds the application's credentials to request revocation of its refresh and access tokens, then clear local credentials:

```typescript
await tokenManager.signOut()
```

If a revocation request fails, `signOut()` still clears local credentials and rejects. Handle that failure without reporting server-side revocation as complete. A successful response confirms that the revocation requests were accepted. Services that validate an issued access token locally can continue accepting it until expiry. Sign-out does not terminate other application connections.

`TokenManager.clear()` removes locally stored credentials without requesting server revocation. Use it when the intended action is only to forget credentials on this device.

## 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, credentials, and workspace IDs per environment. Set each file's base URLs to the regional hosts provisioned for that workspace:

{% 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-us.concurrence.com
AMIGO_IDENTITY_URL=https://identity.api-us.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. Choose the key's **Role** and its **Access scope**, the permissions it can use. You can assign your own role or a less-privileged one, and the scope starts as the role's full permission set. Owners, admins, and members can create keys.
5. Review the configuration and click **Create API Key**.
6. Copy the key. It is only shown once.

The list can be searched by name or key ID and filtered by role or to your own keys, and it shows each key's status, role, scope, last use, and expiry. **Rotate key** issues a replacement secret with a new expiry, shown once, and revokes the previous secret. **Delete key** removes a key, and you can delete only keys your own account created. An API key cannot create, change, or delete an external integration or its credentials: those requests need a signed-in user or a personal access token, and an API key gets `403`.

{% 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**](https://docs.concurrence.com/developer-guide/platform-api/platform-sdk/quickstart.md)**.** Make your first API call.
* [**Error Handling**](https://docs.concurrence.com/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.
