POST
/
auth
/
reset-password
curl -X POST https://api.authiqa.com/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

​
Overview

This endpoint initiates a password reset flow by sending a reset link to the user’s verified email address. Supports both parent and child accounts with appropriate branding.

​
API Details

​
Request Format

​
email
string
required
Email address for the account
​
parentPublicKey
string
Required only for child accounts
curl -X POST https://api.authiqa.com/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

​
Try It Out

Test the API by providing an email address:

​
email
required
Email address to receive reset link
​
parentPublicKey
Parent public Key (required for child accounts)

​
Process Flow

1

Request Validation

  • Validate email format
  • Check parent public key (if provided)
  • Determine account type
  • Verify email confirmation
  • Check rate limiting
2

Account Validation

For Child Accounts:
  • Validate parent public key
  • Verify parent-child relationship
  • Check parent account status
For Parent Accounts:
  • Ensure no parent public key provided
  • Verify ROOT status
3

Token Generation

  • Generate secure OTP
  • Create encrypted reset token with:
    • Email
    • OTP
    • Parent public key (for child accounts)
  • Build reset link
4

Email Delivery

Parent Accounts:
  • Authiqa-branded email
  • Standard reset template
Child Accounts:
  • Parent organization branding
  • Organization-specific template

​
Response Examples

​
200: Success
{
  "success": true,
  "data": {
    "message": "Password reset link has been sent to your email"
  }
}
​
400: Invalid Request
{
  "success": false,
  "error": {
    "code": "INVALID_EMAIL_FORMAT",
    "message": "Invalid email format"
  }
}
​
429: Rate Limited
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Please wait before requesting another reset link"
  }
}

​
Error Codes

​
Parent Account Errors

​
400 Bad Request
  • INVALID_REQUEST - Parent public key provided for parent account

​
Child Account Errors

​
400 Bad Request
  • MISSING_PARENT_PUBLIC_KEY - Parent public key required
  • INVALID_PARENT_PUBLIC_KEY_FORMAT - Invalid public key format
​
401 Unauthorized
  • INVALID_PARENT_PUBLICI_KEY - Invalid parent public key

​
General Errors

​
400 Bad Request
  • MISSING_REQUEST_BODY - Request body required
  • INVALID_REQUEST_BODY - Invalid JSON format
  • MISSING_REQUIRED_FIELDS - Email field required
  • INVALID_EMAIL_FORMAT - Invalid email format
​
403 Forbidden
  • EMAIL_NOT_VERIFIED - Email verification required
  • ACCOUNT_INACTIVE - Account not active
  • ACCOUNT_LOCKED - Account is locked
​
404 Not Found
  • USER_NOT_FOUND - No account with provided email
​
429 Too Many Requests
  • RATE_LIMIT_EXCEEDED - Wait before requesting again

​
Email Templates

Parent Account Email

  • Authiqa branding
  • Subject: “Reset Your Password - Authiqa”
  • 15-minute expiry notice

Child Account Email

  • Parent organization branding
  • Subject: “Reset Your Password - [Organization]”
  • 15-minute expiry notice

​
Rate Limiting

Limits

  • 1 request per minute per email
  • Token expires after 15 minutes
  • Account locks after 5 failed reset attempts