---
method: POST
path: /api/auth/register
auth: none
area: authentication
---
<!-- source: internal/handlers/auth.go:153 AuthHandler.Register -->

# Register User

Create a new user account.

**Endpoint**: `POST /api/auth/register`
**Auth**: Not required
**Content-Type**: `application/json` or `application/x-www-form-urlencoded`

## Request Body

| Field      | Type   | Required | Description                                               |
| ---------- | ------ | -------- | --------------------------------------------------------- |
| email      | string | Yes      | User's email address                                      |
| username   | string | Yes      | Desired username (3-50 chars)                             |
| password   | string | Yes      | Password (min 8 chars, must meet complexity requirements) |
| first_name | string | No       | User's first name                                         |
| last_name  | string | No       | User's last name                                          |

### Example Request

```json example-request
{
  "email": "user@example.com",
  "username": "john",
  "password": "SecureP@ss123!",
  "first_name": "John",
  "last_name": "Doe"
}
```

## Response (201 Created)

```json example-response
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 604800,
  "user": {
    "id": "uuid-here",
    "email": "user@example.com",
    "username": "john",
    "first_name": "John",
    "last_name": "Doe",
    "role": "user"
  }
}
```

**Set-Cookie Header**:

```
Set-Cookie: token=eyJhbG...; Max-Age=604800; Path=/; HttpOnly
```

**Session Duration**: 7 days (604800 seconds)

**First User**: The first user registered automatically becomes an admin.

## Error Responses

| Code | Description                                            |
| ---- | ------------------------------------------------------ |
| 400  | Invalid email format, weak password, or missing fields |
| 409  | Email or username already exists                       |