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	❌	Set the canonical Platform origin explicitly; the current package default remains the legacy US host
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

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 canonical host for your deployment or to route requests through a proxy. The current SDK default is still https://api.platform.amigo.ai; configure the new origin directly rather than relying on legacy-host behavior:

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.* uses that client's baseUrl. Token exchanges must use the separate identity host, not the Platform resource host:

const identityClient = new AmigoClient({
  apiKey: process.env.AMIGO_API_KEY!,
  workspaceId: process.env.AMIGO_WORKSPACE_ID!,
  baseUrl: 'https://identity.api-us.concurrence.com',
})

Use this client only for identity token helpers; keep workspace resource requests on the Platform client. For loginWithDeviceCode(), pass identityBaseUrl: 'https://identity.api-us.concurrence.com' and the target workspaceId explicitly. See Identity Endpoints for discovery checks during the rollout.

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.

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!,
})

Corresponding .env file:

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

Separate Environments

Use separate .env files per environment:

Development (.env.dev)

AMIGO_API_KEY=dev_api_key
AMIGO_WORKSPACE_ID=dev_workspace_id
AMIGO_BASE_URL=https://platform.api-staging.concurrence.com

Production (.env.prod)

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

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.

Never commit API keys to source control. Use environment variables or a secrets manager.

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. Make your first API call.
• Error Handling. Handle authentication and other errors.