> ## Documentation Index > Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. ```bash theme={null} curl -H "X-API-Key: ago_v1_sk_..." https://your-instance.useago.com/api/v1/users ``` See [API Key Authentication](/security/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 ```json theme={null} { "object": "list", "data": [ { "object": "user", "id": "2e182507-63cb-453c-b6b7-db22cabbea76", "email": "alice@acme.com", "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: ```bash theme={null} curl -H "X-API-Key: ago_v1_sk_..." \ "https://your-instance.useago.com/api/v1/users?organization=Acme+Corporation" ``` Search by name: ```bash theme={null} curl -H "X-API-Key: ago_v1_sk_..." \ "https://your-instance.useago.com/api/v1/users?search=alice" ``` Filter by exact email: ```bash theme={null} curl -H "X-API-Key: ago_v1_sk_..." \ "https://your-instance.useago.com/api/v1/users?email=alice@acme.com" ``` *** ## 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. ```json theme={null} { "object": "user", "id": "2e182507-63cb-453c-b6b7-db22cabbea76", "email": "alice@acme.com", "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](#grant-permissions-to-a-user) 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 ```bash theme={null} curl -X POST -H "X-API-Key: ago_v1_sk_..." -H "Content-Type: application/json" \ -d '{"email":"alice@acme.com","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](#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 ```bash theme={null} 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 ```bash theme={null} 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: ```json theme={null} { "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](/api/organization-api) - List organizations and email domains * [Public API Overview](/api/public-api-v1) - Authentication and general API usage * [API Key Authentication](/security/api-key-authentication) - Create and manage API keys