User Management - CGIAR Risk Intelligence Tool

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 pageMinimum: 1
Maximum: 60 (Cognito limit)
Default: 60

nextToken

string

Pagination cursor from the previous responseOmit for first page.

Response

data

object

data.users

array

Array of Cognito user objectsEach 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

curl -X GET "https://api.example.com/api/admin/users?limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "data": {
    "users": [
      {
        "Username": "[email protected]",
        "Attributes": [
          { "Name": "email", "Value": "[email protected]" },
          { "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

string

required

Email address for the new user (used as username, will be lowercased)Format: Valid emailExample: [email protected]

temporaryPassword

string

required

Temporary password (minimum 8 characters)Must meet Cognito password policy. The user must change this on first login.Min length: 8Example: 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 statusTypically FORCE_CHANGE_PASSWORD (user must change password on first login)

Example Request

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

Example Response

{
  "Username": "[email protected]",
  "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: [email protected]

Response

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

Example Request

curl -X GET https://api.example.com/api/admin/users/[email protected] \
  -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 updateExample: [email protected]

Request Body

attributes

object

Key-value map of Cognito user attributes to updateUse standard Cognito attribute names (e.g. email, name, phone_number) or custom attributes (e.g. custom:role).Example:

{
  "email": "[email protected]",
  "name": "Jane Doe",
  "custom:organization": "CGIAR"
}

Response

{
  "message": "User updated successfully."
}

Example Request

curl -X PUT https://api.example.com/api/admin/users/[email protected] \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "email": "[email protected]",
      "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 deleteExample: [email protected]

Response

{
  "message": "User deleted successfully."
}

Example Request

curl -X DELETE https://api.example.com/api/admin/users/[email protected] \
  -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 enableExample: [email protected]

Response

{
  "message": "User enabled successfully."
}

Example Request

curl -X POST https://api.example.com/api/admin/users/[email protected]/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 disableExample: [email protected]

Response

{
  "message": "User disabled successfully."
}

Example Request

curl -X POST https://api.example.com/api/admin/users/[email protected]/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 resetExample: [email protected]

Request Body

temporaryPassword

string

required

Temporary password (minimum 8 characters, must meet Cognito policy)Example: TempP@ss123!

Response

{
  "message": "Password reset successfully."
}

Example Request

curl -X POST https://api.example.com/api/admin/users/[email protected]/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

Authentication

Assessments

Jobs

Prompts

Admin

​Authentication

​List Users

​Query Parameters

​Response

​Example Request

​Example Response

​Create User

​Request Body

​Response

​Example Request

​Example Response

​Get User

​Path Parameters

​Response

​Example Request

​Update User

​Path Parameters

​Request Body

​Response

​Example Request

​Delete User

​Path Parameters

​Response

​Example Request

​Enable User

​Path Parameters

​Response

​Example Request

​Disable User

​Path Parameters

​Response

​Example Request

​Reset Password

​Path Parameters

​Request Body

​Response

​Example Request

​Error Responses

​User Statuses

​Source Code

Build docs developers (and LLMs) love

Authentication

List Users

Query Parameters

Response

Example Request

Example Response

Create User

Request Body

Response

Example Request

Example Response

Get User

Path Parameters

Response

Example Request

Update User

Path Parameters

Request Body

Response

Example Request

Delete User

Path Parameters

Response

Example Request

Enable User

Path Parameters

Response

Example Request

Disable User

Path Parameters

Response

Example Request

Reset Password

Path Parameters

Request Body

Response

Example Request

Error Responses

User Statuses

Source Code