> ## 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.

# Password Management

> Endpoints for password reset, change, and recovery

The CGIAR Risk Intelligence Tool provides several endpoints for password management, including forgot password flow, password reset, forced password change on first login, and authenticated password change.

***

## Forgot Password

<api>POST /api/auth/forgot-password</api>

Initiates the forgot password flow by sending a 6-digit verification code to the user's registered email address.

### Authentication

This is a public endpoint that does not require authentication.

### Rate Limiting

This endpoint is rate-limited to **5 requests per minute** per IP address.

### Request Body

**email** `string` *required*

Registered email address

A verification code will be sent to this address if it exists in the system. The email is automatically lowercased and trimmed.

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

### Request Example

```bash theme={null}
curl -X POST https://api.example.com/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'
```

### Response

#### Success Response (200 OK)

**message** `string`

Confirmation message

The response is intentionally vague to prevent user enumeration. It returns the same message whether or not the email exists in the system.

```json theme={null}
{
  "message": "If this email is registered, a reset code has been sent."
}
```

### Error Responses

**429 Too Many Requests**

**Rate limit exceeded** — More than 5 requests in 1 minute

```json theme={null}
{
  "statusCode": 429,
  "message": "Too many requests",
  "error": "Too Many Requests"
}
```

### Notes

* The verification code is valid for a limited time (typically 24 hours)
* The response is identical whether or not the email exists, to prevent account enumeration attacks
* Check your spam folder if you don't receive the email

***

## Reset Password

<api>POST /api/auth/reset-password</api>

Completes the forgot password flow by providing the verification code received via email and setting a new password.

### Authentication

This is a public endpoint that does not require authentication.

### Rate Limiting

This endpoint is rate-limited to **5 requests per minute** per IP address.

### Request Body

**username** `string` *required*

Username or email address of the account to reset

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

**code** `string` *required*

6-digit verification code sent via email

This code was sent by the `/api/auth/forgot-password` endpoint.

**Example:** `123456`

**newPassword** `string` *required*

New password to set

Must be at least 8 characters long and meet Cognito password policy requirements (typically includes uppercase, lowercase, numbers, and special characters).

**Example:** `NewP@ssw0rd!`

### Request Example

```bash theme={null}
curl -X POST https://api.example.com/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user@example.com",
    "code": "123456",
    "newPassword": "NewP@ssw0rd!"
  }'
```

### Response

#### Success Response (200 OK)

**message** `string`

Confirmation message

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

### Error Responses

**400 Bad Request**

**Invalid or expired verification code, or password does not meet policy requirements**

```json theme={null}
{
  "statusCode": 400,
  "message": "Invalid verification code provided, please try again.",
  "error": "Bad Request"
}
```

Or:

```json theme={null}
{
  "statusCode": 400,
  "message": "Password does not meet requirements",
  "error": "Bad Request"
}
```

**429 Too Many Requests**

**Rate limit exceeded** — More than 5 requests in 1 minute

```json theme={null}
{
  "statusCode": 429,
  "message": "Too many requests",
  "error": "Too Many Requests"
}
```

### Notes

* After successfully resetting the password, the user can log in immediately with the new password
* Verification codes expire after a set period (typically 24 hours)
* If the code is invalid or expired, request a new code using `/api/auth/forgot-password`

***

## Complete Password Change (First Login)

<api>POST /api/auth/complete-password-change</api>

Completes the `NEW_PASSWORD_REQUIRED` challenge returned on first login when an admin has created the account with a temporary password.

### Authentication

This is a public endpoint that does not require authentication. However, you must provide the session token from the login challenge response.

### Rate Limiting

This endpoint is rate-limited to **5 requests per minute** per IP address.

### Request Body

**username** `string` *required*

Username returned in the NEW\_PASSWORD\_REQUIRED challenge

This is provided in the login response when `requiresPasswordChange` is true.

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

**session** `string` *required*

Session token returned in the NEW\_PASSWORD\_REQUIRED challenge

This is provided in the login response when `requiresPasswordChange` is true.

**Example:** `AYABe...`

**newPassword** `string` *required*

New permanent password to set

Must be at least 8 characters long and meet Cognito password policy requirements.

**Example:** `NewP@ssw0rd!`

### Request Example

```bash theme={null}
curl -X POST https://api.example.com/api/auth/complete-password-change \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user@example.com",
    "session": "AYABe...",
    "newPassword": "NewP@ssw0rd!"
  }'
```

### Response

#### Success Response (200 OK)

After successfully setting the new password, the user is automatically authenticated and receives tokens:

**accessToken** `string`

Cognito JWT access token

**refreshToken** `string`

Cognito refresh token

**expiresIn** `number`

Token expiration time in seconds (typically 3600)

**requiresPasswordChange** `boolean`

Always `false` after successful password change

```json theme={null}
{
  "accessToken": "eyJraWQiOiJxYz...",
  "refreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ...",
  "expiresIn": 3600,
  "requiresPasswordChange": false
}
```

### Error Responses

**400 Bad Request**

**Invalid session or password does not meet policy requirements**

```json theme={null}
{
  "statusCode": 400,
  "message": "Invalid session for the user.",
  "error": "Bad Request"
}
```

**429 Too Many Requests**

**Rate limit exceeded** — More than 5 requests in 1 minute

```json theme={null}
{
  "statusCode": 429,
  "message": "Too many requests",
  "error": "Too Many Requests"
}
```

### Notes

* This endpoint is only used during the first login after an admin creates an account
* The session token is short-lived and expires if not used promptly
* After successfully changing the password, the user is automatically logged in with full access tokens

***

## Change Password (Authenticated)

<api>POST /api/auth/change-password</api>

Changes the authenticated user's password. The user must provide their current password for verification.

### Authentication

**Required:** This endpoint requires a valid Bearer token in the `Authorization` header.

```
Authorization: Bearer <access_token>
```

### Rate Limiting

This endpoint is not rate-limited.

### Request Body

**previousPassword** `string` *required*

Current (existing) password of the authenticated user

Must be correct to authorize the password change.

**Example:** `OldP@ssw0rd!`

**proposedPassword** `string` *required*

New password to set

Must be at least 8 characters long and meet Cognito password policy requirements.

**Example:** `NewP@ssw0rd!`

### Request Example

```bash theme={null}
curl -X POST https://api.example.com/api/auth/change-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJraWQiOiJxYz..." \
  -d '{
    "previousPassword": "OldP@ssw0rd!",
    "proposedPassword": "NewP@ssw0rd!"
  }'
```

### Response

#### Success Response (200 OK)

**message** `string`

Confirmation message

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

### Error Responses

**400 Bad Request**

**New password does not meet Cognito policy requirements**

```json theme={null}
{
  "statusCode": 400,
  "message": "Password does not meet requirements",
  "error": "Bad Request"
}
```

**401 Unauthorized**

**Invalid or missing Bearer token, or incorrect previous password**

```json theme={null}
{
  "statusCode": 401,
  "message": "Incorrect username or password.",
  "error": "Unauthorized"
}
```

Or if the token is missing/invalid:

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}
```

### Notes

* The current password must be provided for security verification
* After changing the password, existing access tokens remain valid until they expire
* The user does not need to log in again after changing their password
* Password policy typically requires:
  * Minimum 8 characters
  * At least one uppercase letter
  * At least one lowercase letter
  * At least one number
  * At least one special character


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