Users API

List, look up, pre-create user accounts, and manage their permissions via the Public API

Access user accounts via the Public API. List users, filter by organization or email, retrieve individual profiles, create or update a user before their first login, and grant or revoke their permissions.

Authentication

Read endpoints require an API key with the accounts:read scope. Creating or updating a user requires the accounts:write scope.

curl -H "X-API-Key: ago_v1_sk_..." https://your-instance.useago.com/api/v1/users

See API Key Authentication for setup instructions.

---

List Users

Get a paginated list of users with optional filtering.

GET /api/v1/users

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
page_size	integer	50	Items per page (max 100)
organization	string	—	Filter by organization UUID or name (case-insensitive)
email	string	—	Filter by exact email address
search	string	—	Search by email, first name, or last name (case-insensitive)

Response

{
  "object": "list",
  "data": [
    {
      "object": "user",
      "id": "2e182507-63cb-453c-b6b7-db22cabbea76",
      "email": "[e-mail]",
      "first_name": "Alice",
      "last_name": "Smith",
      "is_customer": true,
      "email_domain": "acme.com",
      "organization": {
        "id": "e1b7d9bf-c3ee-4339-ad43-84632d65f800",
        "name": "Acme Corporation"
      },
      "created_at": "2024-01-15T10:00:00+00:00"
    }
  ],
  "has_more": false,
  "total": 1
}

Response Fields

Field	Type	Description
id	string (UUID)	User identifier
email	string	User’s email address
first_name	string	First name
last_name	string	Last name
is_customer	boolean	Whether this user is a customer (end user)
email_domain	string or null	Domain extracted from the user’s email
organization	object or null	The organization this user belongs to (id and name), or null if unassigned
created_at	string (ISO 8601)	Account creation timestamp

Examples

List users in a specific organization:

curl -H "X-API-Key: ago_v1_sk_..." \
  "https://your-instance.useago.com/api/v1/users?organization=Acme+Corporation"

Search by name:

curl -H "X-API-Key: ago_v1_sk_..." \
  "https://your-instance.useago.com/api/v1/users?search=alice"

Filter by exact email:

curl -H "X-API-Key: ago_v1_sk_..." \
  "https://your-instance.useago.com/api/v1/users?email=[e-mail]"

---

Get User

Get a single user by ID.

GET /api/v1/users/{user_id}

Path Parameters

Parameter	Type	Description
user_id	string (UUID)	User identifier

Response

The single-user response also includes the user’s currently assigned permissions.

{
  "object": "user",
  "id": "2e182507-63cb-453c-b6b7-db22cabbea76",
  "email": "[e-mail]",
  "first_name": "Alice",
  "last_name": "Smith",
  "is_customer": true,
  "email_domain": "acme.com",
  "organization": {
    "id": "e1b7d9bf-c3ee-4339-ad43-84632d65f800",
    "name": "Acme Corporation"
  },
  "created_at": "2024-01-15T10:00:00+00:00",
  "permissions": [
    {
      "id": "a3f1c9d2-1b4e-4a6c-9d8f-2c5b7e0a1f33",
      "name": "support",
      "display_name": "Support"
    }
  ]
}

---

Create or Update a User

Create a user, or update the existing one matched by email, with pre-assigned information. The user is matched by email at first login and reused, so no duplicate is created. Returns 201 when a new user is created and 200 when an existing user is updated.

POST /api/v1/users

Requires the accounts:write scope.

Body Parameters

Parameter	Type	Description
email	string	The user’s email. Required. Used as the matching key.
first_name	string	First name
last_name	string	Last name
organization_id	string (UUID)	Organization to assign. If omitted, the user is auto-linked from their email domain when they don’t already have an organization.
permission_ids	array of string (UUID)	Permissions to assign. This replaces the user’s existing permissions. To add a permission without removing the others, use Grant Permissions instead.
additional_info	object	Arbitrary metadata, merged into the user’s existing metadata
business_context	object	Business data, merged into the user’s existing business context
is_reviewer	boolean	Reviewer access (the user must also be an admin)
is_viewer	boolean	Read-only admin access

Admin (staff) status cannot be set through the API.

Example

curl -X POST -H "X-API-Key: ago_v1_sk_..." -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]","first_name":"Alice","permission_ids":["e1b7d9bf-c3ee-4339-ad43-84632d65f800"]}' \
  "https://your-instance.useago.com/api/v1/users"

The response body is the same user object returned by Get User.

---

Grant Permissions to a User

Add one or more permissions to a user without removing the ones they already have. Re-granting a permission the user already holds has no effect.

POST /api/v1/users/{user_id}/permissions

Requires the accounts:write scope.

Path Parameters

Parameter	Type	Description
user_id	string (UUID)	User identifier

Body Parameters

Parameter	Type	Description
permission_ids	array of string (UUID)	Permissions to add. Required, non-empty.

Example

curl -X POST -H "X-API-Key: ago_v1_sk_..." -H "Content-Type: application/json" \
  -d '{"permission_ids":["a3f1c9d2-1b4e-4a6c-9d8f-2c5b7e0a1f33"]}' \
  "https://your-instance.useago.com/api/v1/users/2e182507-63cb-453c-b6b7-db22cabbea76/permissions"

The response is the updated user object, including its full permissions list.

---

Revoke a Permission

Remove a single permission from a user, leaving the rest unchanged.

DELETE /api/v1/users/{user_id}/permissions/{permission_id}

Requires the accounts:write scope.

Path Parameters

Parameter	Type	Description
user_id	string (UUID)	User identifier
permission_id	string (UUID)	Permission to remove

Example

curl -X DELETE -H "X-API-Key: ago_v1_sk_..." \
  "https://your-instance.useago.com/api/v1/users/2e182507-63cb-453c-b6b7-db22cabbea76/permissions/a3f1c9d2-1b4e-4a6c-9d8f-2c5b7e0a1f33"

The response is the updated user object, including its remaining permissions list.

---

MCP Tools

These endpoints are also available as MCP tools for AI agent integrations:

Tool	Description
list_users	List users with filters for organization, email, and search
get_user	Get a single user by ID, including its assigned permissions
upsert_user	Create or update a user (requires accounts:write)
add_user_permissions	Grant permissions to a user without removing existing ones (requires accounts:write)
remove_user_permission	Revoke a single permission from a user (requires accounts:write)

---

Error Handling

All endpoints return errors in the standard format:

{
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "User not found with ID '00000000-0000-0000-0000-000000000000'.",
    "param": "user_id",
    "doc_url": "https://ago.mintlify.app/api/errors#not_found"
  }
}

Status	Code	Description
403	insufficient_scope	API key missing the required scope (accounts:read to read, accounts:write to create or update)
404	not_found	User not found or invalid UUID
422	validation_error / missing_required_parameter / invalid_value	Missing or empty email, or an unknown organization or permission ID

---

Related Documentation

• Organization API - List organizations and email domains
• Public API Overview - Authentication and general API usage
• API Key Authentication - Create and manage API keys