# API Contract (Auth-enabled)

All endpoints are JSON. Most routes require the HttpOnly cookie `player`, which is issued after successful register/login. Legacy player rows are given `legacy-xxxxxxxx` usernames during migration; they must register/login to get a valid auth cookie.

## Auth
POST /api/auth/register  
POST /api/auth/login  
POST /api/auth/logout

- Register accepts optional `adminKey`; when it matches `ADMIN_PASSWORD`, the account is marked `IsAdmin=true` and can use admin APIs. If an `adminKey` is supplied but wrong (or ADMIN_PASSWORD unset), registration returns 400.

## State
GET /api/state (public)

## Player (requires auth)
GET /api/me  (returns id, displayName, username, isAdmin)  
POST /api/me/name

## Suggestions (requires auth + phase gating)
GET /api/suggestions/mine  
POST /api/suggestions  
DELETE /api/suggestions/{id}  
PUT /api/suggestions/{id} (non-admin: own suggestion, Suggest phase only; admin: any time, any suggestion)  
GET /api/suggestions/all

## Votes (requires auth + phase gating)
GET /api/votes/mine  
POST /api/votes

## Results (requires auth + phase gating)
GET /api/results

## Admin (requires admin account or admin key)
POST /api/admin/phase  
POST /api/admin/reset  
POST /api/admin/factory-reset  

Admin APIs accept either an authenticated admin user (cookie) or, for compatibility, `X-Admin-Key`/`key` matching `ADMIN_PASSWORD`.