Authentication

The HardWire API uses session-based authentication powered by Better Auth.

Overview

All API endpoints (except /api/liveness) require authentication. The API uses HTTP-only cookies for session management.

Authentication Flow

Register a new user account:

curl -X POST "http://localhost:3026/api/auth/sign-up/email" \
  -H "Content-Type: application/json" \
  --data '{
    "email": "[email protected]",
    "password": "your-secure-password",
    "name": "Your Name"
  }'

Authenticate with existing credentials:

curl -X POST "http://localhost:3026/api/auth/sign-in/email" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  --data '{
    "email": "[email protected]",
    "password": "your-secure-password"
  }'

The response will set a session cookie that should be included in subsequent requests.

3. Using the Session

Include the session cookie in all authenticated requests:

curl "http://localhost:3026/api/models" \
  -H "Content-Type: application/json" \
  -b cookies.txt

Session Management

Get Current Session

curl "http://localhost:3026/api/auth/session" \
  -H "Content-Type: application/json" \
  -b cookies.txt

Sign Out

curl -X POST "http://localhost:3026/api/auth/sign-out" \
  -H "Content-Type: application/json" \
  -b cookies.txt

MCP Tools Server Authentication

The MCP Tools Server uses service-level authentication. Requests must include a valid X-Service-Key header:

curl -X POST "http://localhost:3027/mcp" \
  -H "Content-Type: application/json" \
  -H "X-Service-Key: your-service-key" \
  --data '{
    "method": "listTools",
    "params": {}
  }'

Note

The service key is configured via the MCP_SERVICE_KEY environment variable.

Error Responses

Status Code	Description
`401`	Unauthorized - Invalid or missing session
`403`	Forbidden - Insufficient permissions

{
  "error": "Unauthorized",
  "message": "Valid session required"
}