# Register user

**POST** `/v1/auth/register` - Register a new user account with email verification. Creates a new user account, sends a 4-digit verification code via email, and creates an EmailVerification record. User must verify their email using the /verify endpoint to complete registration.

#### Request Body

**`email`** string required

User email address (primary identifier). Must be 1-255 characters and valid email format.

**`password`** string required

Password (min 8 chars with complexity, max 72 chars due to bcrypt limit).

**`full_name`** string required

User's full name (1-255 characters).

**`user_name`** string optional

Preferred username (defaults to email prefix if omitted, min 3 chars, max 100 chars). Can only contain lowercase letters, numbers, dots, underscores, and hyphens.

**`organization_id`** string optional

Organization ID to associate the user with (org_ prefixed, 36 characters total).

**`device_information`** object optional

Device tracking information.

**`device`** string optional

Device name (e.g., "Chrome Browser", "iPhone").

**`platform`** string optional

Platform category (e.g., "web", "mobile", "desktop").

**`operating_system`** string optional

Operating system name.

**`device_id`** string optional

Unique device identifier.

**`user_agent`** string optional

User agent string.

**`location`** string optional

Geographic location.

**`latitude`** string optional

Latitude coordinate.

**`longitude`** string optional

Longitude coordinate.

## Returns

A Register Response object containing user details and email verification key.

**`success`** boolean

Indicates if registration was successful.

**`user_id`** string

User ID (prg_ prefixed for pending registration).

**`email`** string

User's email address.

**`email_key`** string

Email verification key (UUID).

**`verification_required`** boolean

Whether email verification is required.

**`type`** string

Verification type. Always `"registration"`.

**`message`** string

Human-readable message.

**`recommended_username`** string

Recommended username if not provided during registration (optional).


```bash
curl -X POST https://api.aitronos.com/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
  "email": "user@company.com",
  "password": "SecurePassword123!",
  "full_name": "John Doe",
  "user_name": "johndoe",
  "organization_id": "org_1234567890abcdef"
}'
```


```python
import requests

response = requests.post(
  "https://api.aitronos.com/v1/auth/register",
  headers={"Content-Type": "application/json"},
  json={
      "email": "user@company.com",
      "password": "SecurePassword123!",
      "full_name": "John Doe",
      "user_name": "johndoe",
      "organization_id": "org_1234567890abcdef"
  }
)

result = response.json()
print(result)
```


```javascript
const response = await fetch('https://api.aitronos.com/v1/auth/register', {
method: 'POST',
headers: {
  'Content-Type': 'application/json'
},
body: JSON.stringify({
  email: 'user@company.com',
  password: 'SecurePassword123!',
  full_name: 'John Doe',
  user_name: 'johndoe',
  organization_id: 'org_1234567890abcdef'
})
});

const result = await response.json();
console.log(result);
```

## Response

200 Success

```json
{
  "success": true,
  "user_id": "prg_abc123def456",
  "email": "user@company.com",
  "email_key": "uuid-12345678-1234-1234-1234-123456789abc",
  "verification_required": true,
  "message": "Registration successful. Please check your email for a 4-digit verification code."
}
```

Errors
## Complete Error Scenarios

### Quick Reference by HTTP Status

| Status | Count | Error Codes |
|  --- | --- | --- |
| **422** | 18 | `VALIDATION_ERROR` (13), `INVALID_PASSWORD_FORMAT` (4), `ORGANIZATION_ACCESS_DENIED` (1) |
| **403** | 1 | `REGISTRATION_RESTRICTED` |
| **404** | 1 | `ORGANIZATION_NOT_FOUND` |
| **409** | 2 | `USER_ALREADY_EXISTS`, `USERNAME_TAKEN` |
| **500** | 4 | `EMAIL_SEND_FAILED` (2), `INTERNAL_ERROR` (2) |


### A. Request Validation Errors (422)

**Error Code:** `VALIDATION_ERROR`

Common validation failures from request body:


```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "email is required",
    "system_message": "Request validation failed",
    "type": "validation_error",
    "status": 422,
    "details": {
      "fields": [
        {"field": "email", "message": "email is required", "type": "missing"}
      ]
    },
    "trace_id": "uuid",
    "timestamp": "2025-11-20T10:00:00Z"
  }
}
```

**Common Validation Messages:**

- `email is required` / `password is required` / `full_name is required`
- `Please enter a valid email address (e.g., user@example.com)`
- `Email address must not exceed 255 characters`
- `Password must be at least 8 characters long`
- `Username can only contain lowercase letters, numbers, dots, underscores, and hyphens`
- `Organization ID must start with 'org_' prefix`


### B. Organization Errors

**404 - Organization Not Found**


```json
{
  "success": false,
  "error": {
    "code": "ORGANIZATION_NOT_FOUND",
    "message": "Organization not found.",
    "system_message": "Organization not found",
    "type": "client_error",
    "status": 404,
    "details": {"organization_id": "org_xxx"},
    "trace_id": "uuid",
    "timestamp": "2025-11-20T10:00:00Z"
  }
}
```

**422 - Organization Not Active**


```json
{
  "success": false,
  "error": {
    "code": "ORGANIZATION_ACCESS_DENIED",
    "message": "You don't have access to this organization.",
    "system_message": "Organization is not active",
    "type": "validation_error",
    "status": 422,
    "details": {"organization_id": "org_xxx"},
    "trace_id": "uuid",
    "timestamp": "2025-11-20T10:00:00Z"
  }
}
```

### C. Registration Restriction (403)

**Error Code:** `REGISTRATION_RESTRICTED`

Occurs when email domain is not registered and no valid invitation exists:


```json
{
  "success": false,
  "error": {
    "code": "REGISTRATION_RESTRICTED",
    "message": "Registration is restricted. Please contact your administrator.",
    "system_message": "Registration is restricted to users with registered domains or valid invitations. Please contact your administrator.",
    "type": "authorization_error",
    "status": 403,
    "details": {"email": "user@example.com"},
    "trace_id": "uuid",
    "timestamp": "2025-11-20T10:00:00Z"
  }
}
```

### D. Conflict Errors (409)

**User Already Exists**


```json
{
  "success": false,
  "error": {
    "code": "USER_ALREADY_EXISTS",
    "message": "An account with this email already exists.",
    "system_message": "User with this email already exists",
    "type": "client_error",
    "status": 409,
    "details": {"email": "user@example.com"},
    "trace_id": "uuid",
    "timestamp": "2025-11-20T10:00:00Z"
  }
}
```

**Username Taken**


```json
{
  "success": false,
  "error": {
    "code": "USERNAME_TAKEN",
    "message": "This username is already taken. Please choose another.",
    "system_message": "Username already taken",
    "type": "client_error",
    "status": 409,
    "details": {"username": "johndoe"},
    "trace_id": "uuid",
    "timestamp": "2025-11-20T10:00:00Z"
  }
}
```

### E. Password Strength Errors (422)

**Error Code:** `INVALID_PASSWORD_FORMAT`

Password fails strength requirements:


```json
{
  "success": false,
  "error": {
    "code": "INVALID_PASSWORD_FORMAT",
    "message": "Password does not meet requirements. Please try again.",
    "system_message": "Password must contain at least one special character",
    "type": "validation_error",
    "status": 422,
    "details": {"email": "user@example.com"},
    "trace_id": "uuid",
    "timestamp": "2025-11-20T10:00:00Z"
  }
}
```

**Common System Messages:**

- `Password must be at least 8 characters`
- `Password must not exceed 128 characters`
- `Password must contain at least one special character`
- `Password is too common and easily guessed`


**Common weak passwords detected:** password, 12345678, qwerty, abc123, password123, admin123, letmein, welcome

### F. Email Service Errors (500)

**Error Code:** `EMAIL_SEND_FAILED`

Failed to send verification email:


```json
{
  "success": false,
  "error": {
    "code": "EMAIL_SEND_FAILED",
    "message": "Failed to send email. Please try again later.",
    "system_message": "Failed to send verification email. Please try again later.",
    "type": "server_error",
    "status": 500,
    "details": {"email": "user@example.com"},
    "trace_id": "uuid",
    "timestamp": "2025-11-20T10:00:00Z"
  }
}
```

### G. Internal Server Errors (500)

**Error Code:** `INTERNAL_ERROR`

Unexpected server errors:


```json
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Something went wrong. Please try again later.",
    "system_message": "An unexpected error occurred",
    "type": "server_error",
    "status": 500,
    "details": {},
    "trace_id": "uuid",
    "timestamp": "2025-11-20T10:00:00Z"
  }
}
```

### Testing Checklist


```bash
# Missing fields
curl -X POST https://api.aitronos.com/v1/auth/register -d '{}'

# Invalid email format
curl -X POST https://api.aitronos.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"notanemail","password":"Test123!","full_name":"Test"}'

# Weak password
curl -X POST https://api.aitronos.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@test.com","password":"password123","full_name":"Test"}'

# Unregistered domain
curl -X POST https://api.aitronos.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@unregistered.com","password":"Test123!","full_name":"Test"}'

# Existing email
curl -X POST https://api.aitronos.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"existing@test.com","password":"Test123!","full_name":"Test"}'
```