Classic Authentication

Configure Classic API key credentials, exchange them for a user token, and distinguish this flow from Platform authentication.

For a new Platform project, use Choose Credentials. This retained page owns the Classic flow and its existing links.

This page covers Classic API authentication: create an API key, exchange the key credentials for a user token, and use that token under the user's permissions.

Classic API authentication. This page covers the Classic API's two-tier authentication (API key to JWT). Platform workspace routes can accept keys directly; identity, OAuth2, and session routes have their own credential requirements. See Platform API Authentication.

The Credential Flow

Concurrence uses a two-credential system for secure API access. Your Concurrence representative provisions your organization and its initial Admin user; everything from there is self-serve.

1. Generate an API key (one-time or rotate periodically)

   • Create via the Admin Dashboard or the API endpoint

   • Produces api_key_id and api_key

   • Long-lived credential for machine-to-machine authentication

   • Keep it secret to prevent unauthorized access

2. Exchange the API key for a JWT token (per session or application startup)

   • Call POST /v1/{org}/user/signin_with_api_key with the API key credentials

   • Returns an id_token (a JWT) and its expires_at expiry time

   • Short-lived token representing an authenticated user session

3. Use the JWT in all API calls

   • Include it in the header: Authorization: Bearer {jwt}

   • The JWT grants access to conversations, users, and other endpoints

   • It can act on behalf of other users, as permitted by their roles and permissions

Critical: API Key is not a JWT Token

Wrong: Authorization: Bearer {api_key} Correct: Authorization: Bearer {jwt}

For these Classic routes, exchange the API key for a JWT before using a Bearer header. This instruction does not apply to Platform workspace-key authentication.

Flow

Generating API Keys

A service account makes API keys for use with other services. When your organization is set up in Concurrence, an Admin user is created for adding more users. To confirm you are logged in as the Admin role, check that the tag appears in the top right corner of the admin dashboard.

You have two options for generating API keys.

Admin Dashboard

1. Log in to your service account.

2. Navigate to https://<your-org-id>.amigo.ai/admin/settings.

3. Click Create API Key and select the duration.

4. Store the API key and key ID securely (they cannot be retrieved later).

Programmatic (Recommended)

Permission boundaries API keys cannot impersonate users with higher privileges than the key creator.

Authentication Token Generation

Exchange your API key for a JWT token to authenticate API calls.

Sign in with API key

post

/v1/{organization}/user/signin_with_api_key

Given an organization API key, issue an authorization token for the specified user. The token should then be attached to the Authorization header in subsequent Amigo API calls.

This is an alternative authorization method for users who cannot use the Amigo frontend to login and authenticate.

Authorizations

Path parameters

organizationstringRequired

Header parameters

x-api-keystringRequired

The value of the API key.

x-api-key-idstringRequired

The ID of the API key.

x-user-idstringRequired

The ID of the user to sign in as.

x-mongo-cluster-namestring · nullableOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

id_tokenstringRequired

The ID token that should be attached to the Authorization header for future API calls.

expires_atstring · date-timeRequired

The time at which the token expires.

401

API key not found, is incorrect, or the requested user is not found.

404

Specified organization is not found.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 5 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post/v1/{organization}/user/signin_with_api_key

POST /v1/{organization}/user/signin_with_api_key HTTP/1.1
Host: api.amigo.ai
x-api-key: text
x-api-key-id: text
x-user-id: text
Accept: */*

{
  "id_token": "text",
  "expires_at": "2026-01-01T00:00:00.000Z"
}

Testing with Postman or Scalar

When testing with API clients like Postman, Scalar, or Insomnia, follow the quick start flow below.

Quick start flow

1. Generate an API key using one of the methods above. You will have api_key, api_key_id, and your user_id.

2. Call the signin endpoint to exchange for a JWT (see the embedded reference above).

3. Use the JWT as a Bearer token for all other API calls.

Critical: the signin endpoint uses headers

When calling /user/signin_with_api_key, pass credentials as HTTP headers rather than in the request body:

• x-api-key: {your-api-key}

• x-api-key-id: {your-api-key-id}

• x-user-id: {your-user-id}

The response contains { "id_token": "...", "expires_at": "..." }. The id_token is the JWT you use as the Bearer token.

Where to find credentials

• api_key, api_key_id, and user_id: all available at https://<your-org-id>.amigo.ai/admin/settings/api-keys

• user_id: also available in user details at https://<your-org-id>.amigo.ai/admin/users/{user_id}

Once you have the JWT, use it for all subsequent requests.

Authorization: Bearer {id_token-from-signin-response}

Regional Endpoints and Dedicated Clusters

• Use the regional base URL that matches your organization's residency. See Regions & Endpoints for the full list.

• For tenants on dedicated clusters, include the x-mongo-cluster-name header when instructed (mandatory for Create Organization).

Security Best Practices

API key rotation

1. Create new keys before current keys expire.

2. Transition applications to use the new credentials.

3. Revoke old keys after a successful transition.

4. Automate rotation to prevent authentication failures.

Additional security measures

• Environment variables. Never hardcode credentials.

• Access control. Apply the principle of least privilege.

• Audit logs. Monitor API key usage.

• Secure storage. Use a secret management solution.

Advanced Authentication

Most integrations only need the API key to JWT flow above. The methods in this section cover specialized deployments.

DPoP (Sender-Constrained Tokens)

DPoP belongs to supported Platform identity token flows. It is not an additional step in the Classic API key-to-user-token exchange on this page. Follow the credential and issuer requirements of the identity integration you are implementing; do not apply a Platform token response or proof format to the Classic sign-in endpoint.

See Platform Authentication for the distinction between workspace keys, interactive identity, and the separately scoped OAuth2 flows.

HTTP Basic Authentication (Experimental)

Experimental feature. HTTP Basic Auth is experimental and subject to change. Use the API key to JWT exchange for production integrations.

An alternative authentication method is available using HTTP Basic Auth, which supports cross-organization authorization.

Format:

Authorization: Basic base64({org_id}_{user_id}:{jwt})

The username is {org_id}_{user_id} and the password is the Concurrence-issued JWT that identifies the user.

Key features:

• Combines organization, user, and the user's Concurrence-issued JWT into a single header

• Supports cross-organization authentication (a user in org A authenticating against org B)

• Useful for scenarios where the standard two-step API key to JWT flow is impractical

Example:

# Encode credentials
CREDENTIALS=$(echo -n "${ORG_ID}_${USER_ID}:${JWT}" | base64)

curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/service/' \
     --header "Authorization: Basic ${CREDENTIALS}"

CLI Authentication (Agent Forge)

The current Go Agent Forge CLI targets the Platform API. Use its Platform authentication setup for workspace keys or device authorization.

The configuration below belongs to the legacy Classic workflow and its .env.{env} files. Use the legacy Python CLI when you need supported Classic commands.

Method 1: API key authentication

Set all three API key variables to use API key auth. This method also supports user impersonation via the --user flag.

API_KEY=your-api-key
API_KEY_ID=your-api-key-id
API_KEY_USER_ID=your-user-id

Method 2: Interactive Classic Authentication

Set GOOGLE_TENANT_ID (and omit the API key fields) to use interactive Google Sign-In with device code flow. When using the device code flow, the CLI displays a user code and directs you to Google's device authorization page (https://www.google.com/device). After signing in, you enter the code shown in your terminal and approve the request. Tokens are cached locally (with owner-only file permissions) and refresh automatically.

GOOGLE_TENANT_ID=your-tenant-id

# One-time login per environment
forge auth login -e myorg

# Output:
# Visit: https://www.google.com/device
# Enter code: ABCD-EFGH
# Waiting for authentication...
# Authenticated as [e-mail]

Auth method selection. The CLI picks the auth method based on which environment variables are set. If all three API key fields are present, API key auth is used. Otherwise, interactive Classic auth is used. Subsequent commands reuse cached tokens and refresh them silently.

Impersonation limitation. The --user flag on conversation commands (smoke-test, simulate, simulate-step) requires API key authentication. Interactive Classic auth does not support user impersonation.