Authentication

Amigo implements a two-tiered authentication system for secure API access. This guide covers the authentication workflow and best practices.

Authentication Flow

Step 1: User and Workspace Creation

Note: This part of the process will be handled for you by an Amigo representative.

1. Create a User: Begin by setting up a user profile within the desired workspace. This user profile will represent an individual or entity and hold specific privileges and access rights within Amigo.

2. Set Up a Workspace: Establish or join a workspace, which serves as a collaborative environment for you and others, providing a curated space for data and user activities.

Step 2: API Key Generation

• After setting up the user and workspace, the next step is to create an API key. This key is a unique identifier that allows applications to access the workspace securely and perform operations based on the permissions granted to it. Keep this key secret to prevent unauthorized access.

Step 3: Authentication Token Creation

• Use the generated API key to create an authentication token. This token acts as a pass, granting access to perform actions on behalf of the users it impersonates within Amigo. Tokens are essential for validation, allowing the system to authenticate requests and ensure they are performed by verified entities.

Final Notes

• Security Best Practices: Always safeguard your API keys and authentication tokens. Limit their distribution and rotate them periodically to enhance security.

• User Impersonation: Leverage the authentication token to carry out tasks simulating the identity of other users, as permitted by their roles and permissions.

Regional Endpoints and Dedicated Clusters

• Use the regional base URL that matches your organization’s residency (US/EU/AU). 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).

A service account makes API Keys for using other services. When your organization is set up in Amigo, an Admin user is created for adding more users.

To confirm you're logged in as the Admin role, confirm that you can see the tag in the top right corner of the admin dashboard.

Generating API Keys

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 duration

4. Store the API key and key ID securely (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

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

API-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

Path parameters

organizationstringRequired

Header parameters

x-api-keystringRequired

x-api-key-idstringRequired

x-user-idstringRequired

x-mongo-cluster-nameany ofOptional

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.

stringOptional

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

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

HTTPcURLJavaScriptPython

POST /v1/{organization}/user/signin_with_api_key HTTP/1.1
Host: api.amigo.ai
X-API-KEY: YOUR_API_KEY
X-API-KEY-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
x-api-key: text
x-api-key-id: text
x-user-id: text
Accept: */*

{
  "id_token": "text",
  "expires_at": "2025-10-11T17:24:34.859Z"
}

Security Best Practices

API Key Rotation

1. Create new keys before current keys expire

2. Transition applications to use new credentials

3. Revoke old keys after successful transition

4. Automate rotation to prevent authentication failures

Additional Security Measures

• Environment Variables — Never hardcode credentials

• Access Control — Use principle of least privilege

• Audit Logs — Monitor API key usage

• Secure Storage — Use secret management solutions