Password Management - CGIAR Risk Intelligence Tool

Auto-generate your docs

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

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

string

required

Registered email addressA 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

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)

string

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

{
  "message": "If this email is registered, a reset code has been sent."
}

Error Responses

Rate limit exceeded — More than 5 requests in 1 minute

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

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

string

required

Username or email address of the account to resetExample: user@example.com

string

required

6-digit verification code sent via emailThis code was sent by the /api/auth/forgot-password endpoint.Example: 123456

string

required

New password to setMust 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

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)

string

Confirmation message

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

Error Responses

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

{
  "statusCode": 400,
  "message": "Invalid verification code provided, please try again.",
  "error": "Bad Request"
}

Or:

{
  "statusCode": 400,
  "message": "Password does not meet requirements",
  "error": "Bad Request"
}

Rate limit exceeded — More than 5 requests in 1 minute

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

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

string

required

Username returned in the NEW_PASSWORD_REQUIRED challengeThis is provided in the login response when requiresPasswordChange is true.Example: user@example.com

string

required

Session token returned in the NEW_PASSWORD_REQUIRED challengeThis is provided in the login response when requiresPasswordChange is true.Example: AYABe...

string

required

New permanent password to setMust be at least 8 characters long and meet Cognito password policy requirements.Example: NewP@ssw0rd!

Request Example

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:

string

Cognito JWT access token

string

Cognito refresh token

number

Token expiration time in seconds (typically 3600)

boolean

Always false after successful password change

{
  "accessToken": "eyJraWQiOiJxYz...",
  "refreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ...",
  "expiresIn": 3600,
  "requiresPasswordChange": false
}

Error Responses

Invalid session or password does not meet policy requirements

{
  "statusCode": 400,
  "message": "Invalid session for the user.",
  "error": "Bad Request"
}

Rate limit exceeded — More than 5 requests in 1 minute

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

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

string

required

Current (existing) password of the authenticated userMust be correct to authorize the password change.Example: OldP@ssw0rd!

string

required

New password to setMust be at least 8 characters long and meet Cognito password policy requirements.Example: NewP@ssw0rd!

Request Example

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)

string

Confirmation message

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

Error Responses

New password does not meet Cognito policy requirements

{
  "statusCode": 400,
  "message": "Password does not meet requirements",
  "error": "Bad Request"
}

Invalid or missing Bearer token, or incorrect previous password

{
  "statusCode": 401,
  "message": "Incorrect username or password.",
  "error": "Unauthorized"
}

Or if the token is missing/invalid:

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

​Forgot Password

​Authentication

​Rate Limiting

​Request Body

​Request Example

​Response

​Success Response (200 OK)

​Error Responses

​Notes

​Reset Password

​Authentication

​Rate Limiting

​Request Body

​Request Example

​Response

​Success Response (200 OK)

​Error Responses

​Notes

​Complete Password Change (First Login)

​Authentication

​Rate Limiting

​Request Body

​Request Example

​Response

​Success Response (200 OK)

​Error Responses

​Notes

​Change Password (Authenticated)

​Authentication

​Rate Limiting

​Request Body

​Request Example

​Response

​Success Response (200 OK)

​Error Responses

​Notes

Forgot Password

Authentication

Rate Limiting

Request Body

Request Example

Response

Success Response (200 OK)

Error Responses

Notes

Reset Password

Authentication

Rate Limiting

Request Body

Request Example

Response

Success Response (200 OK)

Error Responses

Notes

Complete Password Change (First Login)

Authentication

Rate Limiting

Request Body

Request Example

Response

Success Response (200 OK)

Error Responses

Notes

Change Password (Authenticated)

Authentication

Rate Limiting

Request Body

Request Example

Response

Success Response (200 OK)

Error Responses

Notes