Authentication

Amigo Authentication Process

Amigo utilizes a robust two-tiered authentication system to ensure secure access. Below is a detailed guide on how to interact with this system:

Step 1: User and Workspace Creation

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

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.

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:

Option 1: Generate via 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 a valid duration time.

4. Securely store the API key and key ID as they cannot be retrieved later

Option 2: Generate Programmatically (Recommended)

Create an API key

post

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:

• User:GetUserInfo for the authenticated user.
• Organization:CreateAPIKey.
• This endpoint requires the authenticated user to have more privileges than the role associated with the API key.

Authorizations

Bearer-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

Path parameters

organizationstringrequired

Header parameters

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.

Body

durationstring · durationrequired

The valid duration of the API key. Should be supplied in the ISO8601 format. Must be between 1 to 90 days.

role_namestringoptional

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.

Default: DefaultAdministratorRole

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.amigo.ai/v1/{organization}/organization/api_key/' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "duration": "text",
    "role_name": "text"
  }'

201

400

401

403

404

422

429

503

201

{
  "api_key_id": "text",
  "api_key": "text",
  "expires_at": "2025-04-03T20:56:01.205Z"
}

Succeeded.

If you've made it this far, congrats! You should now be able to generate authentication tokens to impersonate any user in your organization. Note: API Keys cannot be used to impersonate users with more privilege than the creator of the api key.

Authentication Token Generation

1. Use the Sign in With API Key endpoint to get an authorization token to use for subsequent 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-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

Path parameters

organizationstringrequired

Header parameters

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.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.amigo.ai/v1/{organization}/user/signin_with_api_key' \
  --header 'X-API-KEY: YOUR_API_KEY'

200

401

404

422

429

503

200

{
  "id_token": "text",
  "expires_at": "2025-04-03T20:56:01.205Z"
}

Succeeded.

API Key Rotation Best Practices

For enhanced security:

1. Create a new API key before the current one expires

2. Transition your applications to use the new key

3. Revoke the old key once transitions are complete

4. Automate this process to prevent authentication failures