diff --git a/internal/api/auth_handler.go b/internal/api/auth_handler.go
index 94788b9..83d9560 100644
--- a/internal/api/auth_handler.go
+++ b/internal/api/auth_handler.go
@@ -132,13 +132,41 @@ type WhoamiResponse struct {
 
 // Whoami godoc
 // @Summary      Get current identity
-// @Description  Returns the identity of the authenticated user based on the Authorization header.
+// @Description  Returns complete identity and realtime statistics of the authenticated user.
 // @Description  Supports Admin Token, Master Key, and Child Key (API Key) authentication.
+// @Description  This endpoint is designed for frontend initialization - call once after login
+// @Description  and store the response for subsequent use.
 // @Description
-// @Description  Response varies by token type:
-// @Description  - Admin Token: {"type": "admin", "role": "admin"}
-// @Description  - Master Key: {"type": "master", "id": 1, "name": "...", ...}
-// @Description  - Child Key: {"type": "key", "id": 5, "master_id": 1, "issued_by": "master", ...}
+// @Description  **Response varies by token type:**
+// @Description
+// @Description  **Admin Token:**
+// @Description  - type: "admin"
+// @Description  - role: "admin"
+// @Description  - permissions: ["*"] (full access)
+// @Description
+// @Description  **Master Key:**
+// @Description  - type: "master"
+// @Description  - Basic info: id, name, group, namespaces, status, epoch, max_child_keys, global_qps
+// @Description  - Timestamps: created_at, updated_at
+// @Description  - Realtime stats: requests, tokens, qps, qps_limit, rate_limited
+// @Description
+// @Description  **Child Key (API Key):**
+// @Description  - type: "key"
+// @Description  - Basic info: id, master_id, master_name, group, scopes, namespaces, status
+// @Description  - Security: issued_at_epoch, issued_by, allow_ips, deny_ips, expires_at
+// @Description  - Model limits: model_limits, model_limits_enabled
+// @Description  - Quota: quota_limit, quota_used, quota_reset_at, quota_reset_type
+// @Description  - Usage stats: request_count, used_tokens, last_accessed_at
+// @Description  - Realtime stats: requests, tokens, qps, qps_limit, rate_limited
+// @Description
+// @Description  **Error responses:**
+// @Description  - 401: authorization header required
+// @Description  - 401: invalid authorization header format
+// @Description  - 401: invalid token
+// @Description  - 401: token is not active
+// @Description  - 401: token has expired
+// @Description  - 401: token has been revoked
+// @Description  - 401: master is not active
 // @Tags         auth
 // @Produce      json
 // @Security     AdminAuth