Register

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

{
  "user_id": "<string>",
  "email": "<string>",
  "email_verified": true,
  "name": "<string>",
  "message": "<string>",
  "verification_required": true
}

POST

api

auth

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

{
  "user_id": "<string>",
  "email": "<string>",
  "email_verified": true,
  "name": "<string>",
  "message": "<string>",
  "verification_required": true
}

Overview

Implementation Status: This endpoint is not yet implemented in the codebase.The authentication system currently relies on AWS Cognito User Pool with admin-created users. Self-service registration will be added in a future release.

The register endpoint will allow new users to create accounts in the IGAD Innovation Hub platform. Registration will use AWS Cognito’s sign-up flow with email verification.

Planned Implementation

Expected Request

string

required

User’s email address. Must be unique and will require verification.Format: Valid email addressExample: [email protected]

password

string

required

User’s chosen 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

Example: SecureP@ssw0rd123

name

string

required

User’s full name for display purposes.Example: John Doe

organization

string

User’s organization or institution (optional).Example: IGAD Climate Prediction and Applications Centre

country

string

User’s country (optional). Useful for regional analytics.Example: Kenya

Expected Request Example

{
  "email": "[email protected]",
  "password": "SecureP@ssw0rd123",
  "name": "John Doe",
  "organization": "IGAD ICPAC",
  "country": "Kenya"
}

Expected Response

Success Response (201 Created)

user_id

string

required

Cognito user identifier (sub).

string

required

Registered email address.

email_verified

boolean

required

Always false on registration. User must verify email via code.

name

string

required

User’s display name.

message

string

required

Instructions for email verification.

verification_required

boolean

required

Always true. Indicates user must verify email before login.

Expected Success Response Example

{
  "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "[email protected]",
  "email_verified": false,
  "name": "John Doe",
  "message": "Registration successful. Please check your email for verification code.",
  "verification_required": true
}

Expected Error Responses

400 Bad Request - Email Already Exists

Returned when email is already registered.

{
  "detail": "An account with this email already exists"
}

Cognito Error: UsernameExistsException

400 Bad Request - Invalid Password

Returned when password doesn’t meet requirements.

{
  "detail": "Password does not meet requirements: Must contain uppercase, lowercase, number, and special character"
}

Cognito Error: InvalidPasswordException

400 Bad Request - Invalid Email Format

Returned when email format is invalid.

{
  "detail": "Invalid email format"
}

Cognito Error: InvalidParameterException

429 Too Many Requests - Rate Limit Exceeded

Returned when too many registration attempts.

{
  "detail": "Too many registration attempts. Please try again later."
}

Cognito Error: TooManyRequestsException

500 Internal Server Error

Returned for unexpected registration failures.

{
  "detail": "Registration failed: {error_message}"
}

Planned Implementation Details

The registration will use Cognito’s sign_up API:

from botocore.exceptions import ClientError
import boto3

cognito_client = boto3.client('cognito-idp', region_name='us-east-1')

try:
    response = cognito_client.sign_up(
        ClientId=os.getenv('COGNITO_CLIENT_ID'),
        Username=email,
        Password=password,
        UserAttributes=[
            {'Name': 'email', 'Value': email},
            {'Name': 'name', 'Value': name},
            {'Name': 'custom:organization', 'Value': organization},
            {'Name': 'custom:country', 'Value': country},
        ]
    )
    user_id = response['UserSub']
except ClientError as e:
    error_code = e.response['Error']['Code']
    # Handle specific errors

Email Verification Flow

After registration:

Cognito sends verification email with 6-digit code
User must call /api/auth/verify-email with:
- email
- code
Account becomes active after verification
User can then call /api/auth/login

Custom Attributes

Cognito User Pool should be configured with custom attributes:

custom:organization (String, mutable)
custom:country (String, mutable)
custom:role (String, mutable) - Default: “user”

Custom attributes must be defined in Cognito User Pool before registration endpoint is implemented.

Auto-Confirmation (Optional)

For internal IGAD domains, auto-confirm emails:

if email.endswith('@igad.int'):
    # Auto-confirm for internal users
    cognito_client.admin_confirm_sign_up(
        UserPoolId=os.getenv('COGNITO_USER_POOL_ID'),
        Username=user_id
    )

Email Verification Endpoint (To Be Implemented)

POST /api/auth/verify-email

Request:

{
  "email": "[email protected]",
  "code": "123456"
}

Response (200 OK):

{
  "success": true,
  "message": "Email verified successfully. You can now log in.",
  "email_verified": true
}

Implementation:

cognito_client.confirm_sign_up(
    ClientId=os.getenv('COGNITO_CLIENT_ID'),
    Username=email,
    ConfirmationCode=code
)

Resend Verification Code Endpoint (To Be Implemented)

POST /api/auth/resend-verification

Request:

{
  "email": "[email protected]"
}

Response (200 OK):

{
  "success": true,
  "message": "Verification code resent. Check your email.",
  "delivery": {
    "DeliveryMedium": "EMAIL",
    "Destination": "n***@igad.int"
  }
}

Implementation:

cognito_client.resend_confirmation_code(
    ClientId=os.getenv('COGNITO_CLIENT_ID'),
    Username=email
)

Expected Usage Example

JavaScript (Fetch)

// Step 1: Register
const registerResponse = await fetch('https://api.igad.int/api/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'SecureP@ssw0rd123',
    name: 'John Doe',
    organization: 'IGAD ICPAC',
    country: 'Kenya',
  }),
})

const registerData = await registerResponse.json()

if (registerResponse.ok) {
  console.log('Registration successful:', registerData.message)
  
  // Step 2: Prompt user for verification code
  const verificationCode = prompt('Enter verification code from email:')
  
  // Step 3: Verify email
  const verifyResponse = await fetch('https://api.igad.int/api/auth/verify-email', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: '[email protected]',
      code: verificationCode,
    }),
  })
  
  const verifyData = await verifyResponse.json()
  
  if (verifyResponse.ok) {
    console.log('Email verified. You can now log in.')
    // Redirect to login page
  }
} else {
  console.error('Registration failed:', registerData.detail)
}

Python (Requests)

import requests

# Step 1: Register
register_response = requests.post(
    'https://api.igad.int/api/auth/register',
    json={
        'email': '[email protected]',
        'password': 'SecureP@ssw0rd123',
        'name': 'John Doe',
        'organization': 'IGAD ICPAC',
        'country': 'Kenya'
    }
)

if register_response.status_code == 201:
    print("Registration successful. Check email for verification code.")
    
    # Step 2: Verify email (after receiving code)
    verification_code = input("Enter verification code: ")
    
    verify_response = requests.post(
        'https://api.igad.int/api/auth/verify-email',
        json={
            'email': '[email protected]',
            'code': verification_code
        }
    )
    
    if verify_response.status_code == 200:
        print("Email verified. You can now log in.")
else:
    print(f"Registration failed: {register_response.json()['detail']}")

Current Workaround

Until self-service registration is implemented, users must be created by administrators using:

AWS Console: Cognito User Pools → Users → Create user

AWS CLI:

aws cognito-idp admin-create-user \
  --user-pool-id $COGNITO_USER_POOL_ID \
  --username [email protected] \
  --user-attributes Name=email,[email protected] Name=name,Value="John Doe" \
  --temporary-password TempP@ssw0rd123 \
  --message-action SUPPRESS

Backend Script: Contact system administrator

Admin-created users must change their temporary password on first login via the NEW_PASSWORD_REQUIRED challenge.

POST /api/auth/login - Login after email verification
POST /api/auth/verify-email - Verify email with code (to be implemented)
POST /api/auth/resend-verification - Resend verification code (to be implemented)
POST /api/auth/forgot-password - Reset password

Implementation Checklist

For Developers: Implementation checklist for registration feature

Security Considerations

Password Requirements

Enforce strong password policies:

Minimum 8 characters (consider 12+ for higher security)
Complexity requirements (uppercase, lowercase, number, special char)
Check against common password lists
Prevent reuse of recent passwords

Email Verification

Verification codes expire after 24 hours
Limit resend attempts to prevent abuse
Use Cognito’s built-in email service or configure SES

Rate Limiting

Limit registration attempts per IP: 5 per hour
Limit verification attempts: 3 per email per hour
Implement CAPTCHA for public registration

Data Privacy

Comply with GDPR and data protection regulations
Allow users to delete their accounts
Log registration events for audit trail
Never store passwords in plain text (Cognito handles this)

Reset Password

⌘I

Build docs developers (and LLMs) love

Get started for free Talk to us

Proposals

Proposal Workflow

Documents

Admin

Authentication

Overview

Planned Implementation

Expected Request

Expected Request Example

Expected Response

Success Response (201 Created)

Expected Success Response Example

Expected Error Responses

400 Bad Request - Email Already Exists

400 Bad Request - Invalid Password

400 Bad Request - Invalid Email Format

429 Too Many Requests - Rate Limit Exceeded

500 Internal Server Error

Planned Implementation Details

Email Verification Flow

Custom Attributes

Auto-Confirmation (Optional)

Email Verification Endpoint (To Be Implemented)

POST /api/auth/verify-email

Resend Verification Code Endpoint (To Be Implemented)

POST /api/auth/resend-verification

Expected Usage Example

JavaScript (Fetch)

Python (Requests)

Current Workaround

Implementation Checklist

Security Considerations

Password Requirements

Email Verification

Rate Limiting

Data Privacy

Build docs developers (and LLMs) love

Proposals

Proposal Workflow

Documents

Admin

Authentication

​Overview

​Planned Implementation

​Expected Request

​Expected Request Example

​Expected Response

​Success Response (201 Created)

​Expected Success Response Example

​Expected Error Responses

​400 Bad Request - Email Already Exists

​400 Bad Request - Invalid Password

​400 Bad Request - Invalid Email Format

​429 Too Many Requests - Rate Limit Exceeded

​500 Internal Server Error

​Planned Implementation Details

​AWS Cognito Sign-Up Flow

​Email Verification Flow

​Custom Attributes

​Auto-Confirmation (Optional)

​Email Verification Endpoint (To Be Implemented)

​POST /api/auth/verify-email

​Resend Verification Code Endpoint (To Be Implemented)

​POST /api/auth/resend-verification

​Expected Usage Example

​JavaScript (Fetch)

​Python (Requests)

​Current Workaround

​Related Endpoints

​Implementation Checklist

​Security Considerations

​Password Requirements

​Email Verification

​Rate Limiting

​Data Privacy

Build docs developers (and LLMs) love

Overview

Planned Implementation

Expected Request

Expected Request Example

Expected Response

Success Response (201 Created)

Expected Success Response Example

Expected Error Responses

400 Bad Request - Email Already Exists

400 Bad Request - Invalid Password

400 Bad Request - Invalid Email Format

429 Too Many Requests - Rate Limit Exceeded

500 Internal Server Error

Planned Implementation Details

AWS Cognito Sign-Up Flow

Email Verification Flow

Custom Attributes

Auto-Confirmation (Optional)

Email Verification Endpoint (To Be Implemented)

POST /api/auth/verify-email

Resend Verification Code Endpoint (To Be Implemented)

POST /api/auth/resend-verification

Expected Usage Example

JavaScript (Fetch)

Python (Requests)

Current Workaround

Related Endpoints

Implementation Checklist

Security Considerations

Password Requirements

Email Verification

Rate Limiting

Data Privacy