> ## Documentation Index
> Fetch the complete documentation index at: https://alliancebioversityciat-alliance-risk-analysis-tool.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# User Management

> Admin endpoints for managing Cognito users

The User Management API provides admin-level control over Cognito user accounts, including creation, updates, deletion, and status management.

## Authentication

All endpoints require JWT Bearer token (Cognito) with **admin role**.

***

## List Users

**`GET /api/admin/users`**

Returns a cursor-paginated list of all Cognito users.

### Query Parameters

**limit** `number` (default: 60)

Number of users per page

**Minimum:** 1\
**Maximum:** 60 (Cognito limit)\
**Default:** 60

**nextToken** `string`

Pagination cursor from the previous response

Omit for first page.

### Response

**data** `object`

**data.users** `array`

Array of Cognito user objects

Each user has:

* `Username` (string): Cognito username (typically email or UUID)
* `Attributes` (array): User attributes (email, name, etc.)
* `UserStatus` (string): Account status (CONFIRMED, FORCE\_CHANGE\_PASSWORD, etc.)
* `Enabled` (boolean): Whether the account is enabled
* `UserCreateDate` (string): ISO 8601 creation timestamp
* `UserLastModifiedDate` (string): ISO 8601 last modified timestamp

**data.nextToken** `string`

Cursor for the next page (null if no more results)

**data.total** `number`

Number of users in this page

### Example Request

```bash theme={null}
curl -X GET "https://api.example.com/api/admin/users?limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Example Response

```json theme={null}
{
  "data": {
    "users": [
      {
        "Username": "user@example.com",
        "Attributes": [
          { "Name": "email", "Value": "user@example.com" },
          { "Name": "email_verified", "Value": "true" },
          { "Name": "sub", "Value": "550e8400-e29b-41d4-a716-446655440000" }
        ],
        "UserStatus": "CONFIRMED",
        "Enabled": true,
        "UserCreateDate": "2026-02-15T10:00:00.000Z",
        "UserLastModifiedDate": "2026-03-01T14:30:00.000Z"
      }
    ],
    "nextToken": "eyJwYWdlIjoyLCJsaW1pdCI6MjB9",
    "total": 1
  }
}
```

***

## Create User

**`POST /api/admin/users`**

Creates a new user in Cognito with a temporary password. The user must change their password on first login (NEW\_PASSWORD\_REQUIRED challenge).

### Request Body

**email** `string` *required*

Email address for the new user (used as username, will be lowercased)

**Format:** Valid email

**Example:** `newuser@example.com`

**temporaryPassword** `string` *required*

Temporary password (minimum 8 characters)

Must meet Cognito password policy. The user must change this on first login.

**Min length:** 8

**Example:** `TempP@ss123!`

**sendWelcomeEmail** `boolean` (default: false)

If true, Cognito sends a welcome email with login instructions to the new user

### Response

**Username** `string`

The created user's Cognito username

**UserStatus** `string`

Initial user status

Typically `FORCE_CHANGE_PASSWORD` (user must change password on first login)

### Example Request

```bash theme={null}
curl -X POST https://api.example.com/api/admin/users \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "temporaryPassword": "TempP@ss123!",
    "sendWelcomeEmail": true
  }'
```

### Example Response

```json theme={null}
{
  "Username": "newuser@example.com",
  "UserStatus": "FORCE_CHANGE_PASSWORD"
}
```

***

## Get User

**`GET /api/admin/users/:username`**

Returns full details for a specific Cognito user including attributes, status, groups, and account metadata.

### Path Parameters

**username** `string` *required*

Cognito username (typically the email address or UUID sub)

**Example:** `user@example.com`

### Response

Full Cognito user object with all attributes, groups, and metadata.

### Example Request

```bash theme={null}
curl -X GET https://api.example.com/api/admin/users/user@example.com \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

***

## Update User

**`PUT /api/admin/users/:username`**

Updates one or more Cognito user attributes. Pass only the attributes you want to change.

### Path Parameters

**username** `string` *required*

Cognito username to update

**Example:** `user@example.com`

### Request Body

**attributes** `object`

Key-value map of Cognito user attributes to update

Use standard Cognito attribute names (e.g. `email`, `name`, `phone_number`) or custom attributes (e.g. `custom:role`).

**Example:**

```json theme={null}
{
  "email": "updated@example.com",
  "name": "Jane Doe",
  "custom:organization": "CGIAR"
}
```

### Response

```json theme={null}
{
  "message": "User updated successfully."
}
```

### Example Request

```bash theme={null}
curl -X PUT https://api.example.com/api/admin/users/user@example.com \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "email": "updated@example.com",
      "name": "Jane Doe"
    }
  }'
```

***

## Delete User

**`DELETE /api/admin/users/:username`**

Permanently deletes a user from Cognito. This action is irreversible.

### Path Parameters

**username** `string` *required*

Cognito username to delete

**Example:** `user@example.com`

### Response

```json theme={null}
{
  "message": "User deleted successfully."
}
```

### Example Request

```bash theme={null}
curl -X DELETE https://api.example.com/api/admin/users/user@example.com \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

***

## Enable User

**`POST /api/admin/users/:username/enable`**

Re-enables a previously disabled Cognito user, restoring their ability to sign in.

### Path Parameters

**username** `string` *required*

Cognito username to enable

**Example:** `user@example.com`

### Response

```json theme={null}
{
  "message": "User enabled successfully."
}
```

### Example Request

```bash theme={null}
curl -X POST https://api.example.com/api/admin/users/user@example.com/enable \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

***

## Disable User

**`POST /api/admin/users/:username/disable`**

Disables a Cognito user, preventing them from signing in. Their account and data are preserved.

### Path Parameters

**username** `string` *required*

Cognito username to disable

**Example:** `user@example.com`

### Response

```json theme={null}
{
  "message": "User disabled successfully."
}
```

### Example Request

```bash theme={null}
curl -X POST https://api.example.com/api/admin/users/user@example.com/disable \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

***

## Reset Password

**`POST /api/admin/users/:username/reset-password`**

Sets a new temporary password for the user. On next login, the user will be forced through the NEW\_PASSWORD\_REQUIRED challenge to set a permanent password.

### Path Parameters

**username** `string` *required*

Cognito username whose password to reset

**Example:** `user@example.com`

### Request Body

**temporaryPassword** `string` *required*

Temporary password (minimum 8 characters, must meet Cognito policy)

**Example:** `TempP@ss123!`

### Response

```json theme={null}
{
  "message": "Password reset successfully."
}
```

### Example Request

```bash theme={null}
curl -X POST https://api.example.com/api/admin/users/user@example.com/reset-password \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "temporaryPassword": "NewTemp@ss456!"
  }'
```

***

## Error Responses

**400** `error`

Validation error (invalid email format, password too short, email already exists, etc.)

**401** `error`

Missing or invalid Bearer token

**403** `error`

Forbidden — admin role required

**404** `error`

User not found

## User Statuses

Cognito users can have the following statuses:

| Status | Description |
| - | - |
| `CONFIRMED` | User has confirmed their email and set a permanent password |
| `FORCE_CHANGE_PASSWORD` | User must change their temporary password on next login |
| `UNCONFIRMED` | User has not yet confirmed their email address |
| `ARCHIVED` | User account has been deleted (soft delete) |
| `COMPROMISED` | User credentials have been compromised |
| `UNKNOWN` | Status cannot be determined |

## Source Code

Implementation: `packages/api/src/admin/users.controller.ts`


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