Skip to main content
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

​
email
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: [email protected]

​
Request Example

curl -X POST https://api.example.com/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

​
Response

​
Success Response (200 OK)

​
message
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

​
429 Too Many Requests
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

​
username
string
required
Username or email address of the account to resetExample: [email protected]
​
code
string
required
6-digit verification code sent via emailThis code was sent by the /api/auth/forgot-password endpoint.Example: 123456
​
newPassword
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": "[email protected]",
    "code": "123456",
    "newPassword": "NewP@ssw0rd!"
  }'

​
Response

​
Success Response (200 OK)

​
message
string
Confirmation message
{
  "message": "Password reset successfully."
}

​
Error Responses

​
400 Bad Request
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"
}
​
429 Too Many Requests
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

​
Complete Password Change (First Login)

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 challengeThis is provided in the login response when requiresPasswordChange is true.Example: [email protected]
​
session
string
required
Session token returned in the NEW_PASSWORD_REQUIRED challengeThis is provided in the login response when requiresPasswordChange is true.Example: AYABe...
​
newPassword
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": "[email protected]",
    "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
{
  "accessToken": "eyJraWQiOiJxYz...",
  "refreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ...",
  "expiresIn": 3600,
  "requiresPasswordChange": false
}

​
Error Responses

​
400 Bad Request
Invalid session or password does not meet policy requirements
{
  "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
{
  "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

​
previousPassword
string
required
Current (existing) password of the authenticated userMust be correct to authorize the password change.Example: OldP@ssw0rd!
​
proposedPassword
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)

​
message
string
Confirmation message
{
  "message": "Password changed successfully."
}

​
Error Responses

​
400 Bad Request
New password does not meet Cognito policy requirements
{
  "statusCode": 400,
  "message": "Password does not meet requirements",
  "error": "Bad Request"
}
​
401 Unauthorized
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

Build docs developers (and LLMs) love

Get started for freeTalk to us