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 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

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:

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.

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:

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

Separate Environments

Use separate .env files per environment:

Development (.env.dev)

AMIGO_API_KEY=dev_api_key
AMIGO_WORKSPACE_ID=dev_workspace_id

Production (.env.prod)

AMIGO_API_KEY=prod_api_key
AMIGO_WORKSPACE_ID=prod_workspace_id

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.

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.