Login - Alliance IGAD Innovation Hub

curl --request POST \
  --url https://api.example.com/api/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "username": "<string>",
  "password": "<string>"
}
'

{
  "access_token": "<string>",
  "refresh_token": "<string>",
  "token_type": "<string>",
  "user": {
    "user_id": "<string>",
    "email": "<string>",
    "role": "<string>",
    "name": "<string>",
    "is_admin": true
  },
  "expires_in": 123,
  "requires_password_change": true,
  "session": "<string>",
  "username": "<string>",
  "message": "<string>",
  "status_code": 123,
  "detail": "<string>"
}

POST

api

auth

curl --request POST \
  --url https://api.example.com/api/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "username": "<string>",
  "password": "<string>"
}
'

{
  "access_token": "<string>",
  "refresh_token": "<string>",
  "token_type": "<string>",
  "user": {
    "user_id": "<string>",
    "email": "<string>",
    "role": "<string>",
    "name": "<string>",
    "is_admin": true
  },
  "expires_in": 123,
  "requires_password_change": true,
  "session": "<string>",
  "username": "<string>",
  "message": "<string>",
  "status_code": 123,
  "detail": "<string>"
}

Overview

The login endpoint authenticates users against AWS Cognito User Pool and returns JWT tokens for API access. It uses the ADMIN_USER_PASSWORD_AUTH flow with email-based authentication. Authentication Flow:

Email and password are sent to AWS Cognito
Cognito validates credentials
Returns JWT access token and refresh token
ID token is decoded to extract user information
Admin status is determined based on email

Request

Body Parameters

username

string

required

User’s email address (treated as username). The API handles URL decoding and trimming automatically.Example: user@igad.int

password

string

required

User’s password. Must meet Cognito password requirements:

Minimum 8 characters
At least one uppercase letter
At least one lowercase letter
At least one number
At least one special character

Request Example

{
  "username": "user@igad.int",
  "password": "SecureP@ssw0rd"
}

Response

Success Response (200 OK)

access_token

string

required

JWT access token for authenticating API requests. Valid for 1 hour (3600 seconds).Format: Bearer token (JWT)

refresh_token

string

Refresh token for obtaining new access tokens without re-authentication. Valid for 30 days.Note: Only returned on initial login, not on password change required scenarios.

token_type

string

required

Always returns "bearer". Use in Authorization header as Bearer {access_token}.

user

object

required

User information extracted from Cognito ID token.

Show User Object

user_id

string

Cognito user’s unique identifier (sub claim from JWT).

string

User’s verified email address.

role

string

User role: "admin" or "user". Determines access permissions.

name

string

User’s display name from Cognito attributes.

is_admin

boolean

Flag indicating admin privileges.

expires_in

integer

required

Token expiration time in seconds. Default is 3600 (1 hour).

requires_password_change

boolean

Present when user must change password on first login or admin-forced password reset.If true:

access_token will be empty
session field contains session token for password change
Client must call /api/auth/complete-password-change with session token

session

string

Session token for completing password change challenge. Only present when requires_password_change is true.

username

string

Echo of username/email. Present in password change required scenarios.

message

string

Human-readable message. Present when requires_password_change is true.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNI...",
  "token_type": "bearer",
  "user": {
    "user_id": "b7d8f6e4-3a2c-4b9d-8e1f-5c6a7d8e9f0a",
    "email": "user@igad.int",
    "role": "user",
    "name": "John Doe",
    "is_admin": false
  },
  "expires_in": 3600
}

Password Change Required Example

{
  "access_token": "",
  "token_type": "bearer",
  "user": {
    "user_id": "",
    "email": "user@igad.int",
    "role": "user",
    "name": "IGAD User",
    "is_admin": false
  },
  "expires_in": 0,
  "requires_password_change": true,
  "session": "AYABeE...",
  "username": "user@igad.int",
  "message": "Password change required"
}

Error Responses

status_code

integer

detail

string

401 Unauthorized - Invalid Credentials

Returned when username/password combination is incorrect.

{
  "detail": "Invalid credentials"
}

Cognito Error: NotAuthorizedException

401 Unauthorized - User Not Found

Returned when user does not exist in Cognito User Pool.

{
  "detail": "User not found"
}

Cognito Error: UserNotFoundException

500 Internal Server Error - Authentication Error

Returned for other Cognito authentication failures.

{
  "detail": "Authentication error: {error_code}"
}

Possible Cognito Errors:

UserNotConfirmedException - Email not verified
PasswordResetRequiredException - Admin-forced password reset
TooManyRequestsException - Rate limit exceeded

500 Internal Server Error - Generic Failure

Returned for unexpected errors.

{
  "detail": "Login failed: {error_message}"
}

Implementation Details

AWS Cognito Integration

The endpoint uses the following Cognito configuration:

Region: us-east-1
Auth Flow: ADMIN_USER_PASSWORD_AUTH
User Pool ID: From COGNITO_USER_POOL_ID environment variable
Client ID: From COGNITO_CLIENT_ID environment variable

Code Reference: backend/app/tools/auth/routes.py:39

Token Handling

Cognito returns three tokens:

Access Token - Used for API authentication (1 hour expiry)
ID Token - Contains user claims (decoded for user info)
Refresh Token - Used to obtain new access tokens (30 days expiry)

ID Token Claims Used:

sub → user_id
email → email
name → name

Admin Role Assignment

Admin status is determined by checking email against hardcoded list:

is_admin = email in [
    "test@example.com",
    "admin@igad.int",
    "user@igad.int",
    "j.cadavid@cgiar.org",
]

Code Reference: backend/app/tools/auth/routes.py:97

Admin role assignment is currently hardcoded. Consider moving to Cognito User Groups for production.

Password Change Challenge

When Cognito returns ChallengeName: NEW_PASSWORD_REQUIRED:

User is in FORCE_CHANGE_PASSWORD state (first login or admin reset)
Response includes session token
Client must call /api/auth/complete-password-change with:
- username
- session
- new_password

Code Reference: backend/app/tools/auth/routes.py:67

Usage Example

cURL

curl -X POST https://api.igad.int/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user@igad.int",
    "password": "SecureP@ssw0rd"
  }'

JavaScript (Fetch)

const response = await fetch('https://api.igad.int/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    username: 'user@igad.int',
    password: 'SecureP@ssw0rd',
  }),
})

const data = await response.json()

if (response.ok) {
  // Store tokens
  localStorage.setItem('accessToken', data.access_token)
  localStorage.setItem('refreshToken', data.refresh_token)
  
  // Check for password change required
  if (data.requires_password_change) {
    // Redirect to password change flow
    handlePasswordChange(data.session, data.username)
  } else {
    // Proceed to dashboard
    console.log('Logged in as:', data.user.email)
  }
} else {
  console.error('Login failed:', data.detail)
}

Python (Requests)

import requests

response = requests.post(
    'https://api.igad.int/api/auth/login',
    json={
        'username': 'user@igad.int',
        'password': 'SecureP@ssw0rd'
    }
)

if response.status_code == 200:
    data = response.json()
    access_token = data['access_token']
    
    # Use token for authenticated requests
    headers = {'Authorization': f'Bearer {access_token}'}
    user_response = requests.get(
        'https://api.igad.int/api/auth/me',
        headers=headers
    )
else:
    print(f"Login failed: {response.json()['detail']}")

POST /api/auth/refresh-token - Refresh access token using refresh token
POST /api/auth/complete-password-change - Complete password change challenge
GET /api/auth/me - Get current user information
POST /api/auth/logout - Logout user session

Security Considerations

Important Security Notes:

Always use HTTPS in production
Never log passwords or tokens
Store tokens securely (httpOnly cookies recommended over localStorage)
Implement token refresh before expiry
Clear tokens on logout

Token Storage

Recommended: Store in httpOnly secure cookies Alternative: localStorage with XSS protections Avoid: Regular cookies accessible to JavaScript

Rate Limiting

Cognito enforces rate limits. Handle TooManyRequestsException with exponential backoff.

Email Handling

The API handles:

URL-encoded emails (user%40igad.int → user@igad.int)
Leading/trailing whitespace
Case-insensitive email matching

Code Reference: backend/app/tools/auth/routes.py:44

User Management

⌘I

​Overview

​Request

​Body Parameters

​Request Example

​Response

​Success Response (200 OK)

​Successful Login Example

​Password Change Required Example

​Error Responses

​401 Unauthorized - Invalid Credentials

​401 Unauthorized - User Not Found

​500 Internal Server Error - Authentication Error

​500 Internal Server Error - Generic Failure

​Implementation Details

​AWS Cognito Integration

​Token Handling

​Admin Role Assignment

​Password Change Challenge

​Usage Example

​cURL

​JavaScript (Fetch)

​Python (Requests)

​Related Endpoints

​Security Considerations

​Token Storage

​Rate Limiting

​Email Handling

Overview

Request

Body Parameters

Request Example

Response

Success Response (200 OK)

Successful Login Example

Password Change Required Example

Error Responses

401 Unauthorized - Invalid Credentials

401 Unauthorized - User Not Found

500 Internal Server Error - Authentication Error

500 Internal Server Error - Generic Failure

Implementation Details

AWS Cognito Integration

Token Handling

Admin Role Assignment

Password Change Challenge

Usage Example

cURL

JavaScript (Fetch)

Python (Requests)

Related Endpoints

Security Considerations

Token Storage

Rate Limiting

Email Handling