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:

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

stringOptional

or

nullOptional

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

201

Succeeded.

application/json

400

The organization has reached the maximum API key limit.

401

Invalid authorization credentials.

403

Missing required permissions.

404

The specified organization or role does not exist.

422

Invalid request path parameter or request body 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}/organization/api_key/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 58

{
  "duration": "text",
  "role_name": "DefaultAdministratorRole"
}

{
  "api_key_id": "text",
  "api_key": "text",
  "expires_at": "2025-05-21T00:49:10.582Z"
}

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.

stringOptional

or

nullOptional

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
Accept: */*

{
  "id_token": "text",
  "expires_at": "2025-05-21T00:49:10.582Z"
}

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