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.
The Credential Flow
Concurrence uses a two-credential system for secure API access. Your Concurrence representative provisions your organization and its initial Admin user. Use the steps below to create credentials and authenticate.
Generate an API key (one-time or rotate periodically)
Create via the Admin Dashboard or the API endpoint
Produces
api_key_idandapi_keyLong-lived credential for machine-to-machine authentication
Keep it secret to prevent unauthorized access
Exchange the API key for a JWT token (per session or application startup)
Call
POST /v1/{org}/user/signin_with_api_keywith the API key credentialsReturns an
id_token(a JWT) and itsexpires_atexpiry timeShort-lived token representing an authenticated user session
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
Flow
Create or rotate an organization API key through the authorized administration path.
Exchange the key for a JWT from a trusted application.
Use the JWT for authenticated HTTP calls or the documented realtime WebSocket subprotocol.
Keep long-lived keys out of browser bundles. The operation reference below defines the request contract.
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.
Log in to your service account.
Navigate to
https://<your-org-id>.amigo.ai/admin/settings.Click Create API Key and select the duration.
Store the API key and key ID securely (they cannot be retrieved later).
Use an existing authorized Classic session to create a key through the API key creation contract. Check its permission requirements and store the returned credentials securely. For initial access, follow the Admin Dashboard tab.
API Key Creation Contract
Create a new API key for the given organization. This API key authorizes the organization to retrieve a per-user access token for users in this organization which allows the users to access most of Amigo's API endpoints. This API key is valid for the duration specified in the request. There's no way to extend the duration of an API key. The API key is not retrievable after issuance, so please keep it in a secure location.
Each organization has a maximum limit of 20 API keys.
Permissions
This endpoint requires the following permissions:
Organization:CreateAPIKey.- This endpoint requires the authenticated user to have more privileges than the role associated with the API key.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
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.
[]An optional name for the API key for easier identification by users.
The valid duration of the API key. Should be supplied in the ISO8601 format. Must be between 1 to 90 days.
The name of the role associated with the key. When using this API key to authenticate, it can only authenticate for users with roles that are less permissive than this role.
DefaultAdministratorRoleSucceeded.
An identifier for this API key. You must present this along with the API key to authenticate.
The API key. This is only visible once and is not retrievable later. Please store safely.
Expiration time of the API key in UTC.
The organization has reached the maximum API key limit.
Invalid authorization credentials.
Missing required permissions.
The specified organization or role does not exist.
A related operation is in progress.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 5 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/organization/api_key/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 72
{
"name": "text",
"duration": "text",
"role_name": "DefaultAdministratorRole"
}{
"api_key_id": "text",
"api_key": "text",
"expires_at": "2026-01-01T00:00:00.000Z"
}Authentication Token Generation
Exchange your API key for a JWT token to authenticate API calls.
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.
The value of the API key.
The ID of the API key.
The ID of the user to sign in as.
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.
[]Succeeded.
The ID token that should be attached to the Authorization header for future API calls.
The time at which the token expires.
API key not found, is incorrect, or the requested user is not found.
Specified organization is not found.
Invalid request path parameter failed validation.
The user has exceeded the rate limit of 5 requests per minute for this endpoint.
The service is going through temporary maintenance.
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
Generate an API key using one of the methods above. You will have
api_key,api_key_id, and youruser_id.Call the signin endpoint to exchange for a JWT (see the embedded reference above).
Use the JWT as a Bearer token for all other API calls.
Once you have the JWT, use it for all subsequent requests.
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-nameheader when instructed (mandatory for Create Organization).
Security Best Practices
API key rotation
Create new keys before current keys expire.
Transition applications to use the new credentials.
Revoke old keys after a successful transition.
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)
An alternative authentication method is available using HTTP Basic Auth, which supports cross-organization authorization.
Format:
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:
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.
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.
Last updated
Was this helpful?

