Skip to main content

Client Registration

Client registration in MicDots is admin-controlled only. Admins create client accounts by providing email, name, and password. The system automatically registers the client and sends login credentials via email.

BASE API ENDPOINT

/api/v1/client/invite

How Client Registration Works​

Admin-Only Registration

In Epic 1, only administrators can create client accounts. There is no self-registration. Admins create accounts and the system emails login credentials to clients.

Registration Flow:

  1. Admin creates client account via POST /api/v1/client/invite
  2. System creates account with provided credentials
  3. System sends email to client with login credentials
  4. Client logs in using credentials from email
  5. Client can start creating text-to-audio requests

Create Client Account (Admin Only)​

Endpoint: POST /api/v1/client/invite

Description: Admin creates a new client account. The system automatically registers the client and sends login credentials via email.

Headers:

Authorization: Bearer ADMIN_ACCESS_TOKEN
Content-Type: application/json

Request Body:

{
  "email": "client@example.com",
  "password": "SecurePassword123!",
  "name": "John Doe"
}

Request Body Fields:

  • email (string, required) - Client email address (must be unique)
  • password (string, required) - Password for the client account (must meet password requirements)
  • name (string, required) - Client's full name

Response: 201 Created

{
  "success": true,
  "data": {
    "clientId": "uuid-here",
    "email": "client@example.com",
    "name": "John Doe",
    "roles": ["client"],
    "emailConfirmed": false,
    "createdAt": "2024-01-22T14:30:00Z"
  },
  "message": "Client account created successfully. Login credentials have been sent to client@example.com"
}

Error Response: 400 Bad Request (Validation Error)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "email": ["The Email field is required."],
      "password": [
        "Password must be at least 8 characters and contain uppercase, lowercase, digit, and special character."
      ],
      "name": ["The Name field is required."]
    }
  }
}

Error Response: 409 Conflict (Email Already Exists)

{
  "success": false,
  "error": {
    "code": "EMAIL_ALREADY_EXISTS",
    "message": "A client with this email address already exists."
  }
}

Error Response: 403 Forbidden (Non-Admin User)

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Only administrators can create client accounts."
  }
}

Password Requirements​

When creating client accounts, passwords must meet the following requirements:

  • Minimum 8 characters
  • At least one uppercase letter (A-Z)
  • At least one lowercase letter (a-z)
  • At least one digit (0-9)
  • At least one special character (!@#$%^&*)

Valid Password Examples:

  • SecurePass123!
  • MyP@ssw0rd
  • Client2024#Strong

Invalid Password Examples:

  • password (no uppercase, digit, or special character)
  • PASSWORD123 (no lowercase or special character)
  • Pass1! (less than 8 characters)

Email Notification​

When an admin creates a client account, the system automatically sends an email to the client with their login credentials.

Email Template​

The system sends a welcome email to the client with login credentials.

See Welcome Email Template for full details.

Client Registration Flow​

Testing with cURL​

Create Client Account (Admin)​

curl -X POST http://localhost:5000/api/v1/client/invite \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN" \
  -d '{
    "email": "newclient@example.com",
    "password": "SecurePassword123!",
    "name": "John Doe"
  }'

Expected Response:

{
  "success": true,
  "data": {
    "clientId": "550e8400-e29b-41d4-a716-446655440000",
    "email": "newclient@example.com",
    "name": "John Doe",
    "roles": ["client"],
    "emailConfirmed": false,
    "createdAt": "2024-01-22T14:30:00Z"
  },
  "message": "Client account created successfully. Login credentials have been sent to newclient@example.com"
}

Security Considerations​

Admin Access Only​

Only users with the admin role can create client accounts:

Password Security​

  • Passwords are hashed using bcrypt before storage
  • Plain-text passwords are only sent once via email during account creation
  • Passwords are never stored in plain text in the database
  • Clients should change their password after first login

Email Security​

  • Welcome emails should be sent via encrypted SMTP (TLS/SSL)
  • Use secure email providers (SendGrid, AWS SES, etc.)
  • Rate limit client creation to prevent spam
  • Log all client creation attempts for audit purposes

Rate Limiting​

Client account creation is rate-limited to prevent abuse:

  • 5 client accounts per admin per hour
  • 50 client accounts per admin per day

Rate Limit Response: 429 Too Many Requests

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Client creation rate limit exceeded. Please try again later.",
    "retryAfter": 3600
  }
}

Error Handling​

Common Errors​

Email Already Exists:

{
  "success": false,
  "error": {
    "code": "EMAIL_ALREADY_EXISTS",
    "message": "A client with this email address already exists."
  }
}

Weak Password:

{
  "success": false,
  "error": {
    "code": "WEAK_PASSWORD",
    "message": "Password does not meet security requirements.",
    "details": {
      "requirements": [
        "Minimum 8 characters",
        "At least one uppercase letter",
        "At least one lowercase letter",
        "At least one digit",
        "At least one special character"
      ]
    }
  }
}

Invalid Email Format:

{
  "success": false,
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Email address format is invalid."
  }
}