API reference for authentication endpoints — register, login, logout, and refresh tokens.

Authentication API

All authentication endpoints are prefixed with /api/auth.

POST /api/auth/register

Create a new Host account.

Request

{
  "email": "[email protected]",
  "password": "securePassword123!",
  "display_name": "John Doe"
}

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "display_name": "John Doe",
  "status": "pending_verification",
  "created_at": "2026-02-21T10:00:00Z"
}

Validation

Field	Required	Rules
email	Yes	Valid email format, unique
password	Yes	Min 12 characters
display_name	Yes	1-100 characters

Errors

400 — Validation error
409 — Email already registered

POST /api/auth/login

Authenticate a Host and receive JWT tokens.

Request

{
  "email": "[email protected]",
  "password": "securePassword123!"
}

Response (200 OK)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "host": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "display_name": "John Doe",
    "status": "active"
  }
}

Errors

401 — Invalid credentials
403 — Email not verified

POST /api/auth/logout

Invalidate the current session.

Headers

Authorization: Bearer <access_token>

Response (204 No Content)

No body returned.

POST /api/auth/refresh

Refresh an expired access token.

Request

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200 OK)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Errors

401 — Invalid or expired refresh token

Token Usage

Including the Token

Include the access token in the Authorization header:

GET /api/host/profile HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Expiry

Access tokens expire after 1 hour (3600 seconds)
Use refresh token to obtain new access token
Refresh tokens are valid for 7 days

Rate Limits

Endpoint	Limit	Window
/auth/register	10 requests	15 minutes
/auth/login	10 requests	15 minutes
/auth/refresh	10 requests	15 minutes

Security Considerations

Password Requirements

Minimum 12 characters
Complexity recommended (mixed case, numbers, symbols)
No maximum length limit

Password Storage

Passwords are hashed using Argon2id before storage:

Resistant to GPU/ASIC attacks
Configurable memory and iteration costs
Salt per password

Token Security

JWTs are signed with HS256
Tokens are invalidated on logout
Token blacklist maintained for security events

Host Profile — Get/Update profile
Will API — Will management

Authentication API

On this page