Register

Create a new user account and receive a session token

POST /api/auth/register

Register

cURL

curl --request POST \
  --url https://api.example.com/api/auth/register \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "password": "<string>",
  "display_name": "<string>"
}
'

200

{
  "success": true,
  "data": {
    "token": "<string>",
    "user": {
      "id": "<string>",
      "email": "<string>",
      "display_name": {},
      "role": "<string>",
      "created_at": "<string>"
    }
  },
  "error": {
    "code": 123,
    "message": "<string>"
  }
}

Description

Creates a new user account with email and password credentials. Returns a session token that can be used for subsequent authenticated requests. The session token is also set as an HTTP-only cookie.

Request Body

email · string · required

User’s email address. Must be a valid email format.

password · string · required

User’s password. Must be at least 8 characters long.

display_name · string

Optional display name for the user.

Response

success · boolean

Indicates whether the request was successful.

data · object

Show properties

token · string

Session token for authentication. Valid for 7 days.

user · object

Show properties

id · string

User’s unique UUID.

email · string

User’s email address.

display_name · string | null

User’s display name.

role · string

User’s role (e.g., “user”, “admin”).

created_at · string

Timestamp when the user was created (ISO 8601 format).

Example Request

curl -X POST https://api.heimdall.example/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "securepassword123",
    "display_name": "John Doe"
  }'

Example Response

{
  "success": true,
  "data": {
    "token": "7a3f9c2e1b5d8a4c6e9f2b3a7c1d5e8f9a2b4c6d8e1f3a5b7c9d2e4f6a8b1c3d5e7f9",
    "user": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "[e-mail]",
      "display_name": "John Doe",
      "role": "user",
      "created_at": "2026-03-12T10:30:00Z"
    }
  }
}

Error Responses

error · object

Show properties

code · number

HTTP status code.

message · string

Error description.

Validation Error (400)

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Validation failed: email: Invalid email address"
  }
}

Email Already Exists (409)

{
  "success": false,
  "error": {
    "code": 409,
    "message": "A user with this email already exists"
  }
}

Internal Server Error (500)

{
  "success": false,
  "error": {
    "code": 500,
    "message": "Internal server error"
  }
}