Signup

Register a new user account with email and password.

Endpoint

POST /api/v1/auth/signup

Headers

Header	Required	Description
Content-Type	Yes	application/json

Request Body

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "display_name": "John Doe",
  "agree_to_terms": true,
  "terms_version": "1.0",
  "idempotency_key": "optional-unique-key"
}

Parameters

Field	Type	Required	Description
email	string	Yes	Valid email address (automatically lowercased)
password	string	Yes	Password meeting strength requirements
display_name	string	No	User's display name
agree_to_terms	boolean	No	Terms acceptance (default: true)
terms_version	string	No	Terms version accepted (default: "1.0")
idempotency_key	string	No	Unique key to prevent duplicate signups

Validations

Email Validation

• Must be valid email format (RFC 5322)
• Automatically lowercased
• Uniqueness check against existing users
• Rate limiting: 3 attempts per 5 minutes per IP

Password Validation

• Minimum 8 characters
• At least one uppercase letter (A-Z)
• At least one lowercase letter (a-z)
• At least one number (0-9)
• Validated server-side before account creation

Terms Acceptance

• Optional but recommended
• Stored in database for compliance
• Terms version tracked for audit

Response

Success (201)

{
  "success": true,
  "data": {
    "user_id": 123,
    "email": "user@example.com",
    "display_name": "John Doe",
    "temporary_token": "temp_token_here",
    "email_verification_required": true,
    "message": "User registered successfully. Please verify your email."
  },
  "message": "User registered successfully. Please verify your email."
}

Error Codes

Status	Code	Description
400	VALIDATION_ERROR	Request validation failed
409	EMAIL_TAKEN	Email already registered
422	INVALID_PASSWORD	Password doesn't meet requirements
429	RATE_LIMITED	Too many signup attempts (3 per 5 minutes)

Data Flow

1. Request Validation

   • Validate email format
   • Validate password strength
   • Check rate limiting

2. Email Uniqueness Check

   • Query database for existing email
   • Return error if email exists

3. Account Creation

   • Create user account
   • Hash password with bcrypt
   • Store display name and metadata

4. Organization Setup

   • Create personal organization
   • Set organization domain from email domain
   • Create default workspace
   • Create default roles (Admin, Developer, Viewer)

5. Membership Creation

   • Create membership linking user to organization
   • Assign Admin role to user
   • Link user to default workspace

6. Email Verification Setup

   • Generate email verification token
   • Create temporary token (10 minute expiry)
   • Queue email verification email

7. Audit Logging

   • Log signup event
   • Record IP address and user agent
   • Store terms acceptance if provided

8. Response

   • Return user ID and temporary token
   • Indicate email verification required

Features

• Automatic personal organization and workspace creation
• Default role assignment (Admin)
• Password strength validation
• Rate limiting protection
• Idempotency key support (prevents duplicate signups)
• Email verification queued automatically
• Terms acceptance tracking
• Audit logging

Next Steps

After successful signup:

1. User receives verification email
2. User verifies email using Verify Email or Verify OTP
3. Upon verification, user receives OAuth2 tokens
4. User can then login normally

Example

curl -X POST https://api.rivergen.com/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "SecurePassword123!",
    "display_name": "Jane Smith",
    "agree_to_terms": true,
    "terms_version": "1.0"
  }'

Related Endpoints

• Verify Email - Verify email with token
• Verify OTP - Verify email with OTP code
• Resend Signup OTP - Resend verification OTP
• Login - Login after verification