Register

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

{
  "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

{
  "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
      }
    }
  }
}

{
  "error": true,
  "response": {
    "code": 400,
    "message": "All fields are required"
  }
}

{
  "error": true,
  "response": {
    "code": 413,
    "message": "Request body too large"
  }
}

{
  "error": true,
  "response": {
    "code": 429,
    "message": "Too many auth attempts, try again later"
  }
}

{
  "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.

Getting Started

Overview

API

SDK

Custom Domain

Register

Register

Request

Parameters

Responses

Errors