User Management - CGIAR Risk Intelligence Tool

Auto-generate your docs

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

number

default:"60"

Number of users per pageMinimum: 1
Maximum: 60 (Cognito limit)
Default: 60

string

Pagination cursor from the previous responseOmit for first page.

Response

object

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

string

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

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": "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

string

required

Email address for the new user (used as username, will be lowercased)Format: Valid emailExample: newuser@example.com

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!

boolean

default:"false"

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

Response

string

The created user’s Cognito username

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": "newuser@example.com",
    "temporaryPassword": "TempP@ss123!",
    "sendWelcomeEmail": true
  }'

Example Response

{
  "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

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

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

string

required

Cognito username to updateExample: user@example.com

Request Body

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": "updated@example.com",
  "name": "Jane Doe",
  "custom:organization": "CGIAR"
}

Response

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

Example Request

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

string

required

Cognito username to deleteExample: user@example.com

Response

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

Example Request

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

string

required

Cognito username to enableExample: user@example.com

Response

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

Example Request

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

string

required

Cognito username to disableExample: user@example.com

Response

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

Example Request

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

string

required

Cognito username whose password to resetExample: user@example.com

Request Body

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/user@example.com/reset-password \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "temporaryPassword": "NewTemp@ss456!"
  }'

Error Responses

error

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

error

Missing or invalid Bearer token

error

Forbidden — admin role required

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

​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

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