> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1eye.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Users

> List, invite, update, and remove users in your workspace.

Manage active and pending users in the workspace associated with your API key. Invite teammates, update names and roles, and remove workspace memberships.

## Base URL

```text theme={null}
https://api.1eye.ai/v1/users
```

## Authentication

All requests require a workspace API key:

```http theme={null}
Authorization: Bearer 1eye_live_xxxxxxxxx
```

The examples use `$API_KEY` for your API key. The key determines the workspace; you do not supply a workspace ID. See [Authentication](https://docs.1eye.ai/api-reference/auth.md).

## Endpoints

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/users` | List active and pending users. |
| `GET` | `/v1/users/{user_id}` | Retrieve a user. |
| `POST` | `/v1/users` | Invite a user by email and role. |
| `PATCH` | `/v1/users/{user_id}` | Update a name or role. |
| `DELETE` | `/v1/users/{user_id}` | Remove a workspace membership. |

## User object

```json theme={null}
{
  "id": "usr_123456789012345678",
  "name": "Jane Doe",
  "email": "jane@snowbricks.example",
  "role": "admin",
  "status": "active",
  "last_login_at": "2026-10-20T17:30:00Z",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-20T18:00:00Z"
}
```

All names, domains, identifiers, amounts, URLs, and timestamps in these examples are illustrative.

| Field | Type | Description |
| - | - | - |
| `id` | string | Workspace User ID (`usr_`). |
| `name` | string or null | Display name; may be unavailable for a pending invitation. |
| `email` | string | Membership email. Read-only after invitation. |
| `role` | string | `admin`, `marketer`, or `viewer`. |
| `status` | string | `active` or `pending` in public responses. |
| `last_login_at` | datetime or null | Last login timestamp in UTC, if available. |
| `created_at` | datetime | Creation timestamp in UTC. |
| `updated_at` | datetime | Last modification timestamp in UTC. |

### Roles

| Role | Purpose |
| - | - |
| `admin` | Workspace administration, subject to the operation's authorization rules. |
| `marketer` | Marketing and GTM work within the assigned permissions. |
| `viewer` | Read access within the assigned permissions. |

Deleted memberships are inaccessible through all Users GET endpoints. User objects do not expose credentials or invitation tokens.

## 1. List users

`GET /v1/users`

```bash theme={null}
curl "https://api.1eye.ai/v1/users?limit=100" \
  -H "Authorization: Bearer $API_KEY"
```

### Query parameters

| Parameter | Type | Description |
| - | - | - |
| `status` | string | `active` or `pending`. Omit to return both. |
| `role` | string | `admin`, `marketer`, or `viewer`. Omit for all roles. |
| `limit` | integer | Results per page. Default: `100`. Range: `1–1000`. |
| `cursor` | string | Opaque cursor returned by the previous page. |

Combine filters to retrieve, for example, pending viewers:

```bash theme={null}
curl "https://api.1eye.ai/v1/users?status=pending&role=viewer&limit=100" \
  -H "Authorization: Bearer $API_KEY"
```

### Example response

**200 OK**

```json theme={null}
{
  "total": 2,
  "data": [
    {
      "id": "usr_987654321098765432",
      "name": null,
      "email": "alex@snowbricks.example",
      "role": "viewer",
      "status": "pending",
      "last_login_at": null,
      "created_at": "2026-10-20T18:00:00Z",
      "updated_at": "2026-10-20T18:00:00Z"
    },
    {
      "id": "usr_123456789012345678",
      "name": "Jane Doe",
      "email": "jane@snowbricks.example",
      "role": "admin",
      "status": "active",
      "last_login_at": "2026-10-20T17:30:00Z",
      "created_at": "2026-10-18T18:00:00Z",
      "updated_at": "2026-10-20T18:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}
```

The unfiltered collection includes active and pending users only. `status=deleted` and `status=all` are invalid.

### Pagination and ordering

Users are ordered by `created_at DESC`, then `id DESC`. Pass `pagination.next_cursor` unchanged with the same filters for the next page. Stop when it is `null`. No configurable sort parameters or offset pagination are supported.

An empty result returns `total: 0`, `data: []`, and `pagination.next_cursor: null`.

## 2. Retrieve a user

`GET /v1/users/{user_id}`

```bash theme={null}
curl "https://api.1eye.ai/v1/users/usr_123456789012345678" \
  -H "Authorization: Bearer $API_KEY"
```

**200 OK** — returns one User object directly, as shown above. Active and pending memberships are accessible. Missing, deleted, or inaccessible IDs all return `404 not_found`.

## 3. Invite a user

`POST /v1/users`

POST accepts exactly `email` and `role`; both are required. It creates a pending membership and sends the existing invitation workflow.

```bash theme={null}
curl -X POST "https://api.1eye.ai/v1/users" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "alex@snowbricks.example",
  "role": "viewer"
}'
```

### Example response

**201 Created**

```json theme={null}
{
  "id": "usr_987654321098765432",
  "name": null,
  "email": "alex@snowbricks.example",
  "role": "viewer",
  "status": "pending",
  "last_login_at": null,
  "created_at": "2026-10-20T18:00:00Z",
  "updated_at": "2026-10-20T18:00:00Z"
}
```

The invited user remains pending until they complete onboarding. The API cannot activate a user by setting `status`.

Email must be valid and at most 254 characters. An active or pending membership with the same normalized email in this workspace causes a 400 validation error. The same email can independently belong to other workspaces.

POST does not accept `name`, `status`, IDs, timestamps, or workspace selectors. A previously deleted email may be invited again as a new pending membership with a new User ID.

## 4. Update a user

`PATCH /v1/users/{user_id}`

PATCH accepts `name`, `role`, or both. At least one must be supplied.

```bash theme={null}
curl -X PATCH "https://api.1eye.ai/v1/users/usr_987654321098765432" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Alex Doe",
  "role": "marketer"
}'
```

### Example response

**200 OK** — returns the complete updated User object.

```json theme={null}
{
  "id": "usr_987654321098765432",
  "name": "Alex Doe",
  "email": "alex@snowbricks.example",
  "role": "marketer",
  "status": "pending",
  "last_login_at": null,
  "created_at": "2026-10-20T18:00:00Z",
  "updated_at": "2026-10-21T18:00:00Z"
}
```

Omitted fields are preserved. Name must be a nonempty string after trimming, no more than 160 characters, without control characters. `null` is invalid for name. Role must be `admin`, `marketer`, or `viewer`.

Email, status, login timestamps, and system fields are read-only. PATCH does not resend an invitation or activate a pending user. Validation is atomic.

## 5. Delete a user

`DELETE /v1/users/{user_id}`

```bash theme={null}
curl -X DELETE "https://api.1eye.ai/v1/users/usr_987654321098765432" \
  -H "Authorization: Bearer $API_KEY"
```

**204 No Content** — the response body is empty.

Deletion removes this workspace membership through soft deletion. The membership immediately disappears from list results and cannot be retrieved, updated, or deleted again through its old ID. Historical attribution remains retained internally. Memberships in other workspaces are unaffected. No restore endpoint is available.

## Administrator protection

Every established workspace must retain at least one active administrator. The last active admin cannot be deleted or demoted. A pending admin does not satisfy this requirement, and admins in another workspace do not count.

All management operations require the appropriate permissions. An API key cannot grant itself permissions it does not possess.

## Errors

| Status | Error code | Description |
| - | - | - |
| 400 | `invalid_parameter` | A request field or query parameter is invalid. |
| 400 | `invalid_request` | An operation would remove or demote the last active administrator. |
| 400 | `invalid_cursor` | The cursor is malformed or does not match the filters. |
| 404 | `not_found` | The user is missing, deleted, or inaccessible. |
| 401 | `authentication_error` | The API key is missing, invalid, or revoked. |
| 403 | `permission_denied` | The key does not have permission for this operation. |
| 429 | `rate_limit_exceeded` | The workspace API rate limit was exceeded. |
| 500 | `internal_error` | An unexpected server error occurred. |
| 503 | `service_unavailable` | The service is temporarily unavailable. |

Errors use the standard [error envelope](https://docs.1eye.ai/api-reference/errors.md). Use `request_id` when contacting support.

### Duplicate email error

```json theme={null}
{
  "error": {
    "code": "invalid_parameter",
    "message": "A user with this email already exists in the Workspace.",
    "param": "email",
    "request_id": "req_123456789012345678"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.