POST
/
auth
/
signup
{
  "username": "parentuser",
  "email": "parent@company.com",
  "password": "SecurePass123!"
}

​
Overview

Create a new user account, either as a parent organization account or a child account under an existing parent. Upon successful signup, users receive an immediate JWT token for authentication.

​
API Details

​
Request Format

​
username
string
required
Username (alphanumeric + underscore only, max 30 chars)
​
email
string
required
Valid email address
​
password
string
required
Password meeting security requirements
​
parentPublicKey
string
Required only for child account creation
​
verifyAuthPath
string
Optional custom verification path for email verification
{
  "username": "parentuser",
  "email": "parent@company.com",
  "password": "SecurePass123!"
}

​
Try It Out

Test the API by filling in the values and clicking Send:

​
username
required
Username for the account
​
email
required
Email address
​
password
password
required
Secure password
​
parentPublicKey
Parent public Key (for child accounts)
​
verifyAuthPath
Custom verification path

​
Code Examples

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

​
Requirements

Username

  • Alphanumeric + underscore only
  • Max 30 characters
  • Must be unique (per parent for child accounts)

Password

  • Minimum 8 characters
  • One uppercase letter
  • One lowercase letter
  • One number
  • One special character

​
Email Verification

Email verification is conditionally sent based on organization settings:
  • Child accounts: Inherits parent’s emailVerificationRequired setting
  • Parent accounts: Default to no verification (can be enabled via organization update)
  • Custom verification path: Use verifyAuthPath to specify custom verification URL

​
Response Examples

​
200: Success
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "data": {
      "userID": "USR_12345",
      "username": "testuser",
      "email": "user@example.com",
      "createdAt": 1729616234,
      "publicKey": "APK_abc123def456_1234567890",
      "emailVerified": false,
      "parentAccount": null,
      "accountType": "parent",
      "emailVerificationSent": false
    }
  }
}
​
200: Success with Email Verification
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "data": {
      "userID": "USR_12345",
      "username": "childuser",
      "email": "child@company.com",
      "createdAt": 1729616234,
      "publicKey": "APK_abc123def456_1234567890",
      "emailVerified": false,
      "parentAccount": "APK_parent123_456",
      "accountType": "child",
      "emailVerificationSent": true
    }
  }
}
​
400: Invalid Format
{
  "success": false,
  "error": {
    "code": "INVALID_USERNAME_FORMAT",
    "message": "Username can only contain letters, numbers, and underscores"
  }
}

​
Error Codes

​
400 Bad Request
  • MISSING_REQUEST_BODY - Request body required
  • INVALID_REQUEST_BODY - Invalid JSON format
  • MISSING_REQUIRED_FIELDS - Missing email/password
  • INVALID_USERNAME_FORMAT - Invalid username format
  • INVALID_EMAIL_FORMAT - Invalid email format
  • INVALID_PASSWORD_FORMAT - Password requirements not met
  • PARENT_NOT_FOUND - Invalid parent public key
  • PARENT_INSUFFICIENT_BALANCE - Parent account has insufficient balance
​
409 Conflict
  • USERNAME_ALREADY_TAKEN - Username exists
  • EMAIL_ALREADY_REGISTERED - Email exists
  • ORGANIZATION_SCOPE_CONFLICT - Email/username exists under parent
​
500 Internal Server Error
  • INTERNAL_SERVER_ERROR - Server error occurred
  • EMAIL_SERVICE_ERROR - Failed to send verification email

​
Key Features

​
Immediate Authentication

  • JWT token provided immediately upon successful signup
  • No need for separate sign-in request
  • Token includes user account type and permissions

​
Conditional Email Verification

  • Email verification only sent when required by organization settings
  • emailVerificationSent flag indicates if verification email was sent
  • Custom verification paths supported via verifyAuthPath

​
Parent-Child Account Hierarchy

  • Child accounts automatically inherit parent organization settings
  • Parent account validation ensures sufficient balance for child operations
  • Automatic organization assignment for child accounts