> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frostauth.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Register

> Create a new Frost Auth console operator account.

# Register

```http theme={null}
POST /api/v1/auth/register
Content-Type: application/json
```

Creates a new operator account for the Frost Auth console. This is not an end-user registration route. It provisions the developer account that manages products, licenses, and settings. Registration signs you in immediately and issues a verification email: the session cookie is set, but the dashboard stays locked until `/api/v1/auth/verify-email` consumes the code.

## Request

```json theme={null}
{
  "userName": "alex.dev",
  "email": "alex@example.com",
  "password": "••••••••",
  "confirmPassword": "••••••••",
  "hcaptchaToken": "P1_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

## Parameters

| Field | Required | Description |
| - | - | - |
| `userName` | Yes | The operator's display name. Stored lowercased; checked against both existing usernames and emails, so neither can be taken twice. |
| `email` | Yes | Email address. Must match a standard email format. |
| `password` | Yes | Account password. Minimum 8 characters. |
| `confirmPassword` | Yes | Must match `password`. Sent by the registration form; the backend does not re-validate it. |
| `hcaptchaToken` | Conditional | hCaptcha response token collected by the widget on the signup form. |

## Responses

```text 201 Created theme={null}
{
  "success": true,
  "response": {
    "data": {
      "user": {
        "id": "cmskeyhvo0001...",
        "name": "alex.dev",
        "email": "alex@example.com",
        "role": "Owner",
        "status": "Active",
        "createdAt": "2026-09-15T08:22:09.118Z",
        "totpEnabled": false
      },
      "recoveryKey": "frostauth-rt-9a8b7c6d5e4f...",
      "verification": {
        "required": true,
        "sent": true,
        "expiresAt": "2026-09-15T08:37:09.118Z",
        "deliveryConfigured": true
      }
    }
  }
}
```

```text 400 Bad Request theme={null}
{
  "error": true,
  "response": {
    "code": 400,
    "message": "All fields are required"
  }
}
```

```text 413 Body Too Large theme={null}
{
  "error": true,
  "response": {
    "code": 413,
    "message": "Request body too large"
  }
}
```

```text 429 Rate Limited theme={null}
{
  "error": true,
  "response": {
    "code": 429,
    "message": "Too many auth attempts, try again later"
  }
}
```

```text 500 Server Error theme={null}
{
  "error": true,
  "response": {
    "code": 500,
    "message": "Registration failed"
  }
}
```

> **Warning:** The `recoveryKey` is shown exactly once and is the only password-reset mechanism — there is no mail server in this stack. Losing it means losing reset access. Treat it like a master password.

## Errors

| HTTP | Message | Cause |
| - | - | - |
| `400` | `All fields are required` | `userName`, `email`, or `password` missing/empty. |
| `400` | `Invalid email format` | Email does not match the required format. |
| `400` | `Password must be at least 8 characters` | Password shorter than 8 characters. |
| `400` | `User already exists` | Email or username already registered. |
| `413` | `Request body too large` | Body exceeds the 10 KB ceiling. |
| `429` | `Too many auth attempts, try again later` | 20 auth requests per 15 minutes per IP. |
| `500` | `Registration failed` | Unhandled exception in the register controller. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.