Users

Create, list, update, and delete users. Manage variables, memories, and authentication tokens.

Users are the individuals who converse with your agents. Each user is scoped to your organization and carries identity details, preferences, variables, and an evolving user model. This page covers the full lifecycle: creating, listing, searching, updating, and deleting users, plus user variables, memories, and email sign-in.

Classic API only: the Platform API does not have user management endpoints. Patient context flows through the World Model instead.

User Management Lifecycle

Create a User

curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/user/' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "user@example.com",
  "role_name": "DefaultUserRole",
  "user_preferences": { "timezone": "America/New_York" }
}'

from amigo_sdk import AmigoClient
from amigo_sdk.models import UserCreateInvitedUserRequest

with AmigoClient() as client:
    result = client.users.create_user(
        UserCreateInvitedUserRequest(
            first_name="Jane",
            last_name="Doe",
            email="user@example.com",
            role_name="DefaultUserRole",
            user_preferences={"timezone": "America/New_York"},
        )
    )
    print(f"User ID: {result.user_id}")

Async Support Async version available with async with AsyncAmigoClient()

import { AmigoClient } from "@amigo-ai/sdk";

const client = new AmigoClient({ ...config });
const result = await client.users.createUser({
  first_name: "Jane",
  last_name: "Doe",
  email: "user@example.com",
  role_name: "DefaultUserRole",
  user_preferences: { timezone: "America/New_York" },
});

console.log(`User ID: ${result.user_id}`);

# Create a user
forge user create -e myorg --first-name "Jane" --last-name "Doe" --email "jane@example.com"

# Create with initial context
forge user create -e myorg --first-name "Jane" --last-name "Doe" --email "jane@example.com" \
  -c "Care Recipient: Bella, Age 5"

# Create with context from file
forge user create -e myorg --first-name "Jane" --last-name "Doe" --email "jane@example.com" \
  -f context.txt

Create a new user

post

/v1/{organization}/user/

Invite a user to the Amigo platform. The endpoint will create a new user in the organization, linked to the supplied email address. The created user will remain in the unverified status and will not have access to most of Amigo's services.

If login_link is not-None, an email containing it will be sent to the user's email with descriptions indicating that this would allow the user to login and start their Amigo experience. Otherwise, no email will be sent.

Permissions

This endpoint requires the following permissions:

User:InviteUser on the user to invite.
The authenticated user must have greater privileges than the role assigned to the new user.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

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.

Path parameters

organizationstringRequired

Header parameters

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: []

Body

first_namestring · min: 1Required

The first name of the user.

last_namestring · min: 1Required

The last name of the user.

emailstring · emailRequired

The email of the user. This email uniquely identifies the user in the organization.

login_linkstring · uri · min: 1 · max: 2083 · nullableOptional

If specified, this link will be sent to the user's email as the link to start their Amigo experience. For Amigo's frontend, this would be the user's organization's login page with their email already filled in.

role_namestringRequired

The role to assign to the user. Only roles that are returned from the Get roles endpoint are allowed.

Responses

201

Succeeded

application/json

user_idstringRequired

The identifier of the new user.

verify_linkstring · nullableRequired

The link sent to the user. Only present if login_link is True in the request.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or role is not found.

409

User with the same email already exists in this organization, or a related operation is in progress.

422

Invalid request path parameter or request body failed validation.

429

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

503

The service is going through temporary maintenance.

post/v1/{organization}/user/

POST /v1/{organization}/user/ 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: 462

{
  "first_name": "text",
  "last_name": "text",
  "email": "name@gmail.com",
  "login_link": "https://example.com",
  "role_name": "text",
  "nonsensitive_user_variables": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "sensitive_user_variables": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "user_preferences": {
    "enable_response_recommendation": false,
    "preferred_language": "aaa",
    "conversations_visible_to_admins": true,
    "user_model_visible_to_admins": true,
    "timezone": "Africa/Abidjan",
    "audio_keyterms": [
      "text"
    ]
  }
}

{
  "user_id": "text",
  "verify_link": "text"
}

List Users

Retrieve users with optional filters:

curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/user/?limit=10&continuation_token=0' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'Accept: application/json'

from amigo_sdk import AmigoClient
from amigo_sdk.models import GetUsersParametersQuery

with AmigoClient() as client:
    users = client.users.get_users(
        GetUsersParametersQuery(limit=10, continuation_token=0)
    )

    for user in users.users:
        print(f"User: {user.email} (ID: {user.user_id})")

Async Support Async version available with async with AsyncAmigoClient()

import { AmigoClient } from "@amigo-ai/sdk";

const client = new AmigoClient({ ...config });
const users = await client.users.getUsers({ limit: 10, continuation_token: 0 });

users.users?.forEach((user) => {
  console.log(`User: ${user.email} (ID: ${user.user_id})`);
});

# List all users
forge user list -e myorg

# Search by name or email
forge user list -e myorg --search "jane"

# Filter by exact email
forge user list -e myorg --email "jane@example.com"

# Limit results
forge user list -e myorg --limit 20

# JSON output for scripting
forge user list -e myorg --json

# Get a single user by ID
forge user get -e myorg -u USER_ID

# Get a single user by email
forge user get -e myorg --email "jane@example.com"

Get users

get

/v1/{organization}/user/

Retrieve all users in an organization.

Permissions

This endpoint is impacted by the following permissions:

Only users that the authenticated user has the User:GetUserInfo permission for are returned.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

Query parameters

user_idstring[]Optional

The ID of the user.

Default: []

emailstring · email[]Optional

The email of the user.

Default: []

limitinteger · max: 100Optional

The maximum number of users to retrieve.

Default: 100

continuation_tokenintegerOptional

The token from the previous request to return the next page of users.

Default: 0

sort_bystring[]Optional

The fields to sort the sets by. Supported fields are first_name, last_name, email, user_stats.num_conversations, user_stats.num_messages, and user_stats.last_message_time. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.

Default: []

Header parameters

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

has_morebooleanRequired

Whether there are more users to retrieve.

continuation_tokeninteger · nullableRequired

A token to supply to the next request to retrieve the next page of users. Only populated if has_more is True.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

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

503

The service is going through temporary maintenance.

get/v1/{organization}/user/

GET /v1/{organization}/user/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "users": [
    {
      "org_id": "text",
      "user_id": "text",
      "first_name": "text",
      "last_name": "text",
      "email": "text",
      "user_stats": {
        "num_conversations": 1,
        "num_messages": 1,
        "last_message_time": "2026-01-01T00:00:00.000Z"
      },
      "role": "text",
      "preferences": {
        "enable_response_recommendation": false,
        "preferred_language": "text",
        "conversations_visible_to_admins": true,
        "user_model_visible_to_admins": true,
        "timezone": "text",
        "audio_keyterms": [
          "text"
        ]
      },
      "nonsensitive_variables": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "sensitive_variables": [
        "text"
      ],
      "enable_actions_access": true
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Search Users

Search for users in the organization by name or email.

Permission required: User:GetUserInfo (only users the caller has permission for are returned)

Parameter

Type

Required

Description

query

string

Yes

Search query to match against names or emails

user_id

array

Filter by specific user IDs (repeatable)

Search users

get

/v1/{organization}/user/search/

Search users in the organization using their names or emails.

Permissions

This endpoint may be impacted by the following permissions:

Only users that the authenticated user has the User:GetUserInfo permission for will be returned.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

Query parameters

querystringRequired

The search query. Any users whose name or email contains the query are returned.

user_idstring[]Optional

The IDs of the users.

Default: []

Header parameters

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

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

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

503

The service is going through temporary maintenance.

get/v1/{organization}/user/search/

GET /v1/{organization}/user/search/?query=text HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "users": [
    {
      "org_id": "text",
      "user_id": "text",
      "first_name": "text",
      "last_name": "text",
      "email": "text",
      "user_stats": {
        "num_conversations": 1,
        "num_messages": 1,
        "last_message_time": "2026-01-01T00:00:00.000Z"
      },
      "role": "text",
      "preferences": {
        "enable_response_recommendation": false,
        "preferred_language": "text",
        "conversations_visible_to_admins": true,
        "user_model_visible_to_admins": true,
        "timezone": "text",
        "audio_keyterms": [
          "text"
        ]
      },
      "nonsensitive_variables": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "sensitive_variables": [
        "text"
      ]
    }
  ]
}

Update User

Modify user details:

curl --request POST \
     --url "https://api.amigo.ai/v1/<YOUR-ORG-ID>/user/<USER-ID>" \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
  "first_name": "Joe",
  "last_name": "Smith",
  "enable_response_recommendation": true,
  "conversations_visible_to_admins": true,
  "timezone": "America/Los_Angeles"
}'

from amigo_sdk import AmigoClient
from amigo_sdk.models import UserUpdateUserInfoRequest

with AmigoClient() as client:
    client.users.update_user(
        user_id,
        UserUpdateUserInfoRequest(
            first_name="Joe",
            last_name="Smith",
            enable_response_recommendation=True,
            conversations_visible_to_admins=True,
            timezone="America/Los_Angeles"
        )
    )

Async Support Async version available with async with AsyncAmigoClient()

import { AmigoClient } from "@amigo-ai/sdk";

const client = new AmigoClient({ ...config });
await client.users.updateUser({
  userId,
  body: {
    first_name: "Joe",
    last_name: "Smith",
    enable_response_recommendation: true,
    conversations_visible_to_admins: true,
    timezone: "America/Los_Angeles",
  },
});

# Update user context with inline strings
forge user update -e myorg -u USER_ID -c "New context entry"

# Update with multiple context entries
forge user update -e myorg -u USER_ID \
  -c "Care Recipient: Bella, Age 5" \
  -c "User ID: xyz789"

# Update context from file
forge user update -e myorg -u USER_ID -f context.txt

Update user info

post

/v1/{organization}/user/{requested_user_id}

Update information about an user. Only fields that are specified in the request are updated.

Permissions

This endpoint requires the following permissions:

User:UpdateUserInfo for the user to update.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

requested_user_idstringRequired

The identifier of the user to update information for.

organizationstringRequired

Header parameters

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: []

Body

first_namestring · min: 1 · nullableOptional

The first name of the user to update. If null, the first name is not modified.

last_namestring · min: 1 · nullableOptional

The last name of the user to update. If null, the last name is not modified.

enable_response_recommendationboolean · nullableOptional

Whether to automatically recommend responses to the user if the user hasn't replied to the coach for a while. If null, the preference is not modified.

preferred_languageany of · nullableOptional

The preferred language for the user. The agent will attempt to converse to the user in this language if set. This field must be in the ISO 639-3 format. If null, erase the user's preferred setting, and the specific language used will be the agent's default spoken language. In order to not update this field, leave it out of the request or set it to an empty object (_NotSet).

Default: {}

string · enum · min: 3 · max: 3OptionalPossible values:

object · _NotSetOptional

A specific type to indicate that a field is not set in the request.

timezoneany of · nullableOptional

The user's timezone in the IANA tz database format. If not specified, the organization's timezone is used.

Default: {}

string · enum · min: 1OptionalPossible values:

object · _NotSetOptional

A specific type to indicate that a field is not set in the request.

conversations_visible_to_adminsboolean · nullableOptional

Whether conversations are visible to the admins. If null, the preference is not modified.

user_model_visible_to_adminsboolean · nullableOptional

Whether the user's user model is visible to the admins. If null, the preference is not modified.

additional_contextstring[] · nullableOptional

A list of additional context to update. If null, the context is not modified.

audio_keytermsstring[] · max: 20 · nullableOptional

A list of keyterms that are easy to get wrong during audio transcriptions that tend to occur commonly in audio sessions using this service. If null, the keyterms are not modified.

Responses

204

Succeeded.

No content

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or user is not found.

409

A related operation is in progress.

422

Invalid request path parameter or request body failed validation.

429

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

503

The service is going through temporary maintenance.

post/v1/{organization}/user/{requested_user_id}

POST /v1/{organization}/user/{requested_user_id} 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: 264

{
  "first_name": "text",
  "last_name": "text",
  "enable_response_recommendation": true,
  "preferred_language": "aaa",
  "timezone": "Africa/Abidjan",
  "conversations_visible_to_admins": true,
  "user_model_visible_to_admins": true,
  "additional_context": [
    "text"
  ],
  "audio_keyterms": [
    "text"
  ]
}

No content

The same endpoint also accepts an additional_context array for feeding facts from your systems into the user model. See the walkthrough on the User Models page:

User Models

Delete User

Remove a user from the organization:

curl --request DELETE \
     --url "https://api.amigo.ai/v1/<YOUR-ORG-ID>/user/<USER-ID>" \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-AN-ADMIN>' \
     --header 'Accept: application/json'

from amigo_sdk import AmigoClient

with AmigoClient() as client:
    client.users.delete_user(user_id)

Async Support Async version available with async with AsyncAmigoClient()

import { AmigoClient } from "@amigo-ai/sdk";

const client = new AmigoClient({ ...config });
await client.users.deleteUser(userId);

forge user delete -e myorg -u USER_ID

Deletion Behavior Deletion returns 204 No Content on success. The user is deleted from the Concurrence system.

Delete an user

delete

/v1/{organization}/user/{requested_user_id}

Delete an user. This endpoint deletes the user from the Amigo system.

Permissions

This endpoint requires the following permissions:

User.DeleteUser on the user to delete.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

requested_user_idstringRequired

The identifier of the user to delete.

organizationstringRequired

Header parameters

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

204

Succeeded.

No content

400

The user is currently active in Actions development.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or user is not found.

409

A related operation is in progress.

422

Invalid request path parameter failed validation.

429

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

503

The service is going through temporary maintenance.

delete/v1/{organization}/user/{requested_user_id}

DELETE /v1/{organization}/user/{requested_user_id} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

No content

Modify User Variables

Upsert or delete user variables. Variables are key-value pairs that are passed to tool invocations. Changes only affect tool invocations that have not yet happened.

Permission required: User:UpdateUserInfo

Modify the variables of an user

post

/v1/{organization}/user/{requested_user_id}/variable

Upsert or delete the user's variables. These changes are only reflected in tool invocations that are not yet made.

Permissions

This endpoint requires the following permissions:

User:UpdateUserInfo for the user to modify variables for.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

requested_user_idstringRequired

The identifier of the user to update information for.

Header parameters

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: []

Body

Responses

204

Succeeded.

No content

400

One or more variables to delete do not exist, or the user has exceeded the limit of 20 nonsensitive variables.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or user is not found.

422

Invalid request path parameter or request body failed validation.

429

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

503

The service is going through temporary maintenance.

post/v1/{organization}/user/{requested_user_id}/variable

POST /v1/{organization}/user/{requested_user_id}/variable 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: 89

{
  "upserts": [
    {
      "name": "text",
      "value": "text",
      "is_secret": true
    }
  ],
  "deletes": [
    {
      "name": "text"
    }
  ]
}

No content

The request body supports two operations:

Field

Type

Description

upserts

array

A list of objects, each containing name, value, and is_secret, to create or update

deletes

array

A list of objects, each containing a name, identifying variables to remove

Get User Memories

Retrieve memories extracted from conversations for a specific user. Memories are key observations the agent stores for future context recall.

Permission note: only memories with references that the caller has Conversation:GetMessage permission on are returned.

Query parameters:

id: filter by specific memory IDs (repeatable)
conversation_id: filter by source conversation (repeatable)
limit: results per page (integer)
continuation_token: pagination token (integer)
sort_by: sort order (repeatable)

Get memories

get

/v1/{organization}/user/{user_id}/memory

Retrieve memories for the specified users.

Permissions

This endpoint may be impacted by the following permissions:

Only memories with references that the authenticated user has the Conversation:GetMessage permission on will be returned.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

user_idstringRequired

The ID of the user to retrieve memories for.

Query parameters

idstring[]Optional

The IDs of the memories to retrieve.

Default: []

conversation_idstring[]Optional

The IDs of the conversations to retrieve memories from.

Default: []

limitinteger · max: 50Optional

The maximum number of memories to retrieve.

Default: 50

continuation_tokenintegerOptional

The token from the previous request to return the next page of memories.

Default: 0

sort_bystring[]Optional

The fields to sort the sets by. Supported fields are conversation_id and created_at. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.

Default: []

Header parameters

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

has_morebooleanRequired

Whether there are more memories to retrieve.

continuation_tokeninteger · nullableRequired

A token to supply to the next request to retrieve the next page of memories. Only populated if has_more is True.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or user is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

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

503

The service is going through temporary maintenance.

get/v1/{organization}/user/{user_id}/memory

GET /v1/{organization}/user/{user_id}/memory HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "memories": [
    {
      "id": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "conversation_id": "text",
      "references": [
        "text"
      ],
      "content": "text",
      "context": "text"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Send a magic link to a user's email for authentication. If the email does not correspond to an existing user, the endpoint succeeds silently to prevent user enumeration.

post

/v1/{organization}/user/signin

Send a magic link to the user's email to sign in. If the specified email doesn't correspond to an user, the endpoint succeeds silently.

Path parameters

organizationstringRequired

Header parameters

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: []

Body

redirect_linkstring · uri · min: 1Required

An Amigo platform link that the user gets redirected to after clicking the login link.

emailstring · emailRequired

Email of the user. This must correspond to an existing, verified user in the Amigo platform.

Responses

200

Succeeded.

application/json

anyOptional

404

Specified organization is not found.

422

Invalid request path parameter or request body failed validation.

503

The service is going through temporary maintenance.

post/v1/{organization}/user/signin

POST /v1/{organization}/user/signin HTTP/1.1
Host: api.amigo.ai
Content-Type: application/json
Accept: */*
Content-Length: 64

{
  "redirect_link": "https://example.com",
  "email": "name@gmail.com"
}

No content

Field

Type

Required

Description

email

string

Yes

Email address to send the magic link to; unknown emails return success without sending, to prevent user enumeration

redirect_link

string

Yes

A Concurrence platform link the user is redirected to after clicking the login link

User Impersonation (CLI)

The --user flag on conversation commands lets you run conversations as an existing user. This is useful for testing user-specific agent behaviors (personalized context, memory, conversation history).

# Smoke test as a specific user
forge conversation smoke-test -s "My Service" -e myorg --user USER_ID -m "Hello"

# Use email instead of ID (auto-resolves)
forge conversation smoke-test -s "My Service" -e myorg --user "jane@example.com" -m "Hello"

# Simulate as a user with temporary additional context
forge conversation simulate -s "My Service" -e myorg --user USER_ID \
  --additional-context "Temporary test context" --max-turns 5

API Key Auth Required User impersonation via --user requires API key authentication. Firebase authentication does not support impersonation. When --user is combined with --additional-context, the user's original context is saved and restored after the test.

Configuration Notes & Best Practices

Timezone Configuration The timezone field uses IANA tz database format (e.g., "America/New_York"). This setting affects how the Concurrence agent interprets time for the user, including timestamps and time-related queries. If not specified, the organization's timezone is used.

Setting

Description

User Preferences

Recommended settings for integrations

Role Assignment

Use DefaultUserRole unless custom roles are required

Custom Roles

Contact the Concurrence team for custom role definitions

Actions Access

enable_actions_access is a read-only flag returned in the List Users (Get Users) response, indicating whether the user has access to actions features. It is not set via the create or update request body.

Practice

Description

User ID Mapping

Save returned user_id and map to internal systems

Token Management

Generate and manage auth tokens per user

State Tracking

Maintain user state for smooth experiences

User Model Management

User Models

PreviousAgents & Context Graphs

NextUser Models

Last updated 24 days ago

Was this helpful?

User Management Lifecycle

Create a User

Create a new user

Permissions

List Users

Get users

Permissions

Search Users

Search users

Permissions

Update User

Update user info

Permissions

Delete User

Delete an user

Permissions

Modify User Variables

Modify the variables of an user

Permissions

Get User Memories

Get memories

Permissions

Sign In with Email

Sign in with email

User Impersonation (CLI)

Configuration Notes & Best Practices

User Model Management