@technomoron/api-server-base 2.0.0-beta.2 → 2.0.0-beta.21

package/docs/swagger/openapi.json

@@ -0,0 +1,1876 @@
+{
+	"openapi": "3.1.0",
+	"info": {
+		"title": "API Server Base",
+		"version": "2.0.0-beta.19",
+		"description": "OpenAPI reference for ApiServer base endpoints and optional modules. Auth, passkey, and oauth modules are optional and require the corresponding module to be enabled in the ApiServer config. Base endpoints are always available."
+	},
+	"servers": [
+		{
+			"url": "http://localhost:3101",
+			"description": "Default local development server"
+		}
+	],
+	"tags": [
+		{
+			"name": "base",
+			"description": "Base endpoints always available in ApiServer."
+		},
+		{
+			"name": "auth",
+			"description": "Optional auth module endpoints. Requires the auth module to be enabled in the ApiServer config."
+		},
+		{
+			"name": "passkey",
+			"description": "Optional passkey module endpoints. Requires passkey support to be enabled in the ApiServer auth config."
+		},
+		{
+			"name": "oauth",
+			"description": "Optional OAuth module endpoints. Requires OAuth support to be enabled in the ApiServer auth config."
+		}
+	],
+	"paths": {
+		"/api/v1/ping": {
+			"get": {
+				"tags": ["base"],
+				"summary": "Health check",
+				"description": "Auth: none. Returns ApiResponse<PingResponseData> with server health and version metadata.",
+				"security": [],
+				"responses": {
+					"200": {
+						"description": "Server is reachable.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/PingResponseData" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/v1/login": {
+			"post": {
+				"tags": ["auth"],
+				"summary": "Login with credentials",
+				"description": "Auth: none. Issues access and refresh tokens for valid credentials.",
+				"security": [],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": { "$ref": "#/components/schemas/LoginRequest" }
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Login succeeded.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/AuthTokensResponseData" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "Missing or invalid credentials.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/v1/refresh": {
+			"post": {
+				"tags": ["auth"],
+				"summary": "Refresh access and refresh tokens",
+				"description": "Auth: required. Reissues tokens using a refresh token supplied in the body or refresh cookie.",
+				"security": [{ "refreshTokenCookie": [] }],
+				"requestBody": {
+					"required": false,
+					"content": {
+						"application/json": {
+							"schema": { "$ref": "#/components/schemas/RefreshRequest" }
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Refresh succeeded.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/AuthTokensResponseData" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "Missing or invalid refresh token.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"403": {
+						"description": "Refresh token expired.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/v1/logout": {
+			"post": {
+				"tags": ["auth"],
+				"summary": "Logout and revoke the refresh token",
+				"description": "Auth: required. Revokes the refresh token supplied in the body or refresh cookie and clears auth cookies.",
+				"security": [{ "refreshTokenCookie": [] }],
+				"requestBody": {
+					"required": false,
+					"content": {
+						"application/json": {
+							"schema": { "$ref": "#/components/schemas/LogoutRequest" }
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Logout succeeded.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/LogoutResponseData" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "Not logged in.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/v1/whoami": {
+			"post": {
+				"tags": ["auth"],
+				"summary": "Resolve the current identity",
+				"description": "Auth: required. Resolves the effective user from the refresh token and optionally refreshes the access token.",
+				"security": [{ "refreshTokenCookie": [] }],
+				"requestBody": {
+					"required": false,
+					"content": {
+						"application/json": {
+							"schema": { "$ref": "#/components/schemas/WhoAmIRequest" }
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Identity resolved.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/WhoAmIResponseData" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "Missing or invalid refresh token.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"403": {
+						"description": "Refresh token expired or user not found.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/v1/impersonations": {
+			"post": {
+				"tags": ["auth"],
+				"summary": "Start impersonating a user",
+				"description": "Auth: strict. Issues tokens for a target user when impersonation is permitted.",
+				"security": [{ "accessTokenBearer": [] }, { "accessTokenCookie": [] }, { "apiKeyBearer": [] }],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": { "$ref": "#/components/schemas/ImpersonateRequest" }
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Impersonation tokens issued.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/AuthTokensResponseData" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "Missing userId or login.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "Authentication required.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"403": {
+						"description": "Impersonation not permitted or user not found.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			},
+			"delete": {
+				"tags": ["auth"],
+				"summary": "Stop impersonating",
+				"description": "Auth: strict. Reissues tokens for the real user to end impersonation.",
+				"security": [{ "accessTokenBearer": [] }, { "accessTokenCookie": [] }, { "apiKeyBearer": [] }],
+				"requestBody": {
+					"required": false,
+					"content": {
+						"application/json": {
+							"schema": { "$ref": "#/components/schemas/ImpersonationEndRequest" }
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Impersonation ended; admin tokens returned.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/AuthTokensResponseData" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "Authentication required.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"403": {
+						"description": "Authenticated user not found.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/v1/passkeys/challenge": {
+			"post": {
+				"tags": ["passkey"],
+				"summary": "Create a passkey challenge",
+				"description": "Auth: none. Creates a passkey challenge for register or authenticate flows.",
+				"security": [],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": { "$ref": "#/components/schemas/PasskeyChallengeRequest" }
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Challenge created.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/PasskeyChallenge" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "Malformed request.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"501": {
+						"description": "Passkey support not configured.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/v1/passkeys/verify": {
+			"post": {
+				"tags": ["passkey"],
+				"summary": "Verify a passkey response",
+				"description": "Auth: none. Verifies a passkey response and issues tokens on success.",
+				"security": [],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": { "$ref": "#/components/schemas/PasskeyVerifyRequest" }
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Passkey verified; tokens issued.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/AuthTokensResponseData" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "Malformed request.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "Passkey verification failed.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"403": {
+						"description": "User not found for passkey verification.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"501": {
+						"description": "Passkey support not configured.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/v1/passkeys": {
+			"get": {
+				"tags": ["passkey"],
+				"summary": "List passkey credentials",
+				"description": "Auth: strict. Returns passkey credentials for the authenticated user.",
+				"security": [{ "accessTokenBearer": [] }, { "accessTokenCookie": [] }, { "apiKeyBearer": [] }],
+				"responses": {
+					"200": {
+						"description": "Credentials for the current user.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/PasskeyListResponseData" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "Authentication required.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"403": {
+						"description": "Authenticated user not found.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"501": {
+						"description": "Passkey management not configured.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/v1/passkeys/{credentialId}": {
+			"delete": {
+				"tags": ["passkey"],
+				"summary": "Delete a passkey credential",
+				"description": "Auth: strict. Deletes the passkey credential identified by the path parameter.",
+				"security": [{ "accessTokenBearer": [] }, { "accessTokenCookie": [] }, { "apiKeyBearer": [] }],
+				"parameters": [
+					{
+						"name": "credentialId",
+						"in": "path",
+						"required": true,
+						"description": "Credential id (base64url).",
+						"schema": { "type": "string" }
+					}
+				],
+				"responses": {
+					"200": {
+						"description": "Credential deleted.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/PasskeyDeleteResponseData" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "Missing or invalid credentialId.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "Authentication required.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"403": {
+						"description": "Authenticated user not found.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"404": {
+						"description": "Passkey not found.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"501": {
+						"description": "Passkey management not configured.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/v1/oauth2/{provider}/start": {
+			"post": {
+				"tags": ["oauth"],
+				"summary": "Begin an external OAuth flow",
+				"description": "Auth: none. Starts an external OAuth flow for the provider.",
+				"security": [],
+				"parameters": [
+					{
+						"name": "provider",
+						"in": "path",
+						"required": true,
+						"description": "OAuth provider identifier.",
+						"schema": { "type": "string" }
+					}
+				],
+				"requestBody": {
+					"required": false,
+					"content": {
+						"application/json": {
+							"schema": { "$ref": "#/components/schemas/OAuthStartRequest" }
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Start payload for the provider.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/OAuthStartResponse" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "Missing provider.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"501": {
+						"description": "OAuth support not configured.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/v1/oauth2/{provider}/callback": {
+			"post": {
+				"tags": ["oauth"],
+				"summary": "Complete an external OAuth flow",
+				"description": "Auth: none. Completes the provider callback and returns the provider result.",
+				"security": [],
+				"parameters": [
+					{
+						"name": "provider",
+						"in": "path",
+						"required": true,
+						"description": "OAuth provider identifier.",
+						"schema": { "type": "string" }
+					}
+				],
+				"requestBody": {
+					"required": false,
+					"content": {
+						"application/json": {
+							"schema": {
+								"type": "object",
+								"additionalProperties": true
+							}
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Provider callback result.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/OAuthCallbackResponse" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "Missing provider.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"501": {
+						"description": "OAuth support not configured.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/v1/oauth2/authorize": {
+			"post": {
+				"tags": ["oauth"],
+				"summary": "Issue an authorization code",
+				"description": "Auth: required. Issues an authorization code for an authenticated user using a refresh token cookie or login credentials.",
+				"security": [{ "refreshTokenCookie": [] }],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": { "$ref": "#/components/schemas/OAuthAuthorizeRequest" }
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Authorization code issued.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/OAuthAuthorizeResponse" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "Invalid request or client configuration.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "User authentication required.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"501": {
+						"description": "OAuth authorization storage not configured.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/v1/oauth2/token": {
+			"post": {
+				"tags": ["oauth"],
+				"summary": "Exchange a code or refresh token",
+				"description": "Auth: none. Exchanges an authorization code or refresh token for OAuth tokens; client authentication may be required.",
+				"security": [],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": { "$ref": "#/components/schemas/OAuthTokenRequest" }
+						},
+						"application/x-www-form-urlencoded": {
+							"schema": { "$ref": "#/components/schemas/OAuthTokenRequest" }
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Token response.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "$ref": "#/components/schemas/OAuthTokenResponse" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "Invalid request.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "Invalid client credentials.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					},
+					"501": {
+						"description": "OAuth token storage not configured.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"allOf": [
+										{ "$ref": "#/components/schemas/ApiResponse" },
+										{
+											"type": "object",
+											"properties": {
+												"data": { "type": "null" }
+											},
+											"required": ["data"]
+										}
+									]
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	},
+	"components": {
+		"securitySchemes": {
+			"accessTokenBearer": {
+				"type": "http",
+				"scheme": "bearer",
+				"bearerFormat": "JWT",
+				"description": "JWT access token via Authorization: Bearer <token>."
+			},
+			"accessTokenCookie": {
+				"type": "apiKey",
+				"in": "cookie",
+				"name": "dat",
+				"description": "Access token cookie (default name \"dat\", configurable via ApiServerConf.accessCookie)."
+			},
+			"refreshTokenCookie": {
+				"type": "apiKey",
+				"in": "cookie",
+				"name": "drt",
+				"description": "Refresh token cookie (default name \"drt\", configurable via ApiServerConf.refreshCookie)."
+			},
+			"apiKeyBearer": {
+				"type": "http",
+				"scheme": "bearer",
+				"description": "API key via Authorization: Bearer apikey-<secret>."
+			}
+		},
+		"schemas": {
+			"SafeUser": {
+				"type": "object",
+				"description": "Filtered user representation returned by storage.filterUser().",
+				"additionalProperties": true
+			},
+			"ApiResponse": {
+				"type": "object",
+				"description": "ApiResponse<T> standard envelope used by all endpoints (success or error). T is the endpoint-specific payload type carried in the data field. Mirrors ApiClientBase.ApiResponseData.",
+				"properties": {
+					"success": {
+						"type": "boolean",
+						"description": "True on success responses."
+					},
+					"code": {
+						"type": "integer",
+						"description": "HTTP status code mirrored in the body."
+					},
+					"message": {
+						"type": "string",
+						"description": "Message string; may be defaulted by the client."
+					},
+					"data": {
+						"description": "Endpoint-specific payload.",
+						"nullable": true
+					},
+					"errors": {
+						"type": "object",
+						"description": "Field-level validation errors keyed by field name.",
+						"additionalProperties": {
+							"type": "string"
+						}
+					}
+				},
+				"required": ["success", "code", "message", "data", "errors"]
+			},
+			"PingResponseData": {
+				"type": "object",
+				"description": "Data payload returned by GET /api/v1/ping.",
+				"properties": {
+					"success": {
+						"type": "boolean",
+						"description": "Always true (redundant with ApiResponse.success)."
+					},
+					"status": {
+						"type": "string",
+						"description": "Health indicator (\"ok\")."
+					},
+					"apiVersion": {
+						"type": "string"
+					},
+					"minClientVersion": {
+						"type": "string"
+					},
+					"uptimeSec": {
+						"type": "number"
+					},
+					"startedAt": {
+						"type": "integer",
+						"format": "int64",
+						"description": "Server start time as milliseconds since epoch."
+					},
+					"timestamp": {
+						"type": "string",
+						"format": "date-time"
+					}
+				},
+				"required": ["success", "status", "uptimeSec", "startedAt", "timestamp"]
+			},
+			"AuthTokensResponseData": {
+				"type": "object",
+				"description": "Access and refresh tokens paired with the effective user.",
+				"properties": {
+					"accessToken": {
+						"type": "string"
+					},
+					"refreshToken": {
+						"type": "string"
+					},
+					"user": {
+						"$ref": "#/components/schemas/SafeUser"
+					}
+				},
+				"required": ["accessToken", "refreshToken", "user"]
+			},
+			"WhoAmIResponseData": {
+				"type": "object",
+				"description": "Identity payload returned by /auth/v1/whoami.",
+				"properties": {
+					"user": {
+						"$ref": "#/components/schemas/SafeUser"
+					},
+					"isImpersonating": {
+						"type": "boolean",
+						"description": "True when the real user differs from the effective user."
+					},
+					"realUser": {
+						"$ref": "#/components/schemas/SafeUser",
+						"nullable": true
+					},
+					"realUserId": {
+						"description": "Identifier of the real user when impersonating.",
+						"nullable": true
+					}
+				},
+				"required": ["user", "isImpersonating"]
+			},
+			"LogoutResponseData": {
+				"type": "object",
+				"description": "Payload returned by /auth/v1/logout.",
+				"properties": {
+					"revoked": {
+						"type": "integer",
+						"description": "Number of refresh tokens revoked."
+					}
+				},
+				"required": ["revoked"]
+			},
+			"LoginRequest": {
+				"type": "object",
+				"properties": {
+					"login": {
+						"type": "string"
+					},
+					"password": {
+						"type": "string"
+					},
+					"domain": {
+						"type": "string",
+						"nullable": true
+					},
+					"fingerprint": {
+						"type": "string",
+						"nullable": true
+					},
+					"label": {
+						"type": "string",
+						"nullable": true
+					},
+					"browser": {
+						"type": "string",
+						"nullable": true
+					},
+					"device": {
+						"type": "string",
+						"nullable": true
+					},
+					"ip": {
+						"type": "string",
+						"nullable": true
+					},
+					"os": {
+						"type": "string",
+						"nullable": true
+					},
+					"keepSession": {
+						"description": "Boolean or TTL controlling refresh cookie persistence.",
+						"nullable": true
+					}
+				},
+				"required": ["login", "password"]
+			},
+			"RefreshRequest": {
+				"type": "object",
+				"properties": {
+					"refreshToken": {
+						"type": "string",
+						"nullable": true
+					},
+					"domain": {
+						"type": "string",
+						"nullable": true
+					},
+					"fingerprint": {
+						"type": "string",
+						"nullable": true
+					},
+					"label": {
+						"type": "string",
+						"nullable": true
+					},
+					"keepSession": {
+						"nullable": true
+					}
+				}
+			},
+			"LogoutRequest": {
+				"type": "object",
+				"properties": {
+					"token": {
+						"type": "string",
+						"description": "Refresh token; falls back to cookie when omitted.",
+						"nullable": true
+					}
+				}
+			},
+			"WhoAmIRequest": {
+				"type": "object",
+				"properties": {
+					"refreshToken": {
+						"type": "string",
+						"nullable": true
+					},
+					"refresh": {
+						"type": "boolean",
+						"description": "Force issuing a new access token even if one is present.",
+						"nullable": true
+					}
+				}
+			},
+			"ImpersonateRequest": {
+				"type": "object",
+				"properties": {
+					"userId": {
+						"description": "Target user id.",
+						"nullable": true
+					},
+					"login": {
+						"type": "string",
+						"description": "Target login identifier.",
+						"nullable": true
+					},
+					"keepSession": {
+						"nullable": true
+					},
+					"domain": {
+						"type": "string",
+						"nullable": true
+					},
+					"fingerprint": {
+						"type": "string",
+						"nullable": true
+					},
+					"label": {
+						"type": "string",
+						"nullable": true
+					},
+					"browser": {
+						"type": "string",
+						"nullable": true
+					},
+					"device": {
+						"type": "string",
+						"nullable": true
+					},
+					"ip": {
+						"type": "string",
+						"nullable": true
+					},
+					"os": {
+						"type": "string",
+						"nullable": true
+					},
+					"clientId": {
+						"type": "string",
+						"nullable": true
+					},
+					"scope": {
+						"description": "Space-delimited or array scope.",
+						"nullable": true
+					},
+					"loginType": {
+						"type": "string",
+						"nullable": true
+					}
+				}
+			},
+			"ImpersonationEndRequest": {
+				"type": "object",
+				"properties": {
+					"keepSession": {
+						"nullable": true
+					},
+					"domain": {
+						"type": "string",
+						"nullable": true
+					},
+					"fingerprint": {
+						"type": "string",
+						"nullable": true
+					},
+					"label": {
+						"type": "string",
+						"nullable": true
+					},
+					"browser": {
+						"type": "string",
+						"nullable": true
+					},
+					"device": {
+						"type": "string",
+						"nullable": true
+					},
+					"ip": {
+						"type": "string",
+						"nullable": true
+					},
+					"os": {
+						"type": "string",
+						"nullable": true
+					},
+					"clientId": {
+						"type": "string",
+						"nullable": true
+					},
+					"scope": {
+						"description": "Space-delimited or array scope.",
+						"nullable": true
+					},
+					"loginType": {
+						"type": "string",
+						"nullable": true
+					}
+				}
+			},
+			"PasskeyChallenge": {
+				"type": "object",
+				"description": "Challenge payload returned when initiating a passkey operation.",
+				"properties": {
+					"challenge": {
+						"type": "string"
+					},
+					"expiresAt": {
+						"type": "string",
+						"format": "date-time",
+						"nullable": true
+					},
+					"userId": {
+						"description": "User identifier for the challenge.",
+						"nullable": true
+					}
+				},
+				"additionalProperties": true,
+				"required": ["challenge"]
+			},
+			"PasskeyCredential": {
+				"type": "object",
+				"description": "Passkey credential entry.",
+				"properties": {
+					"id": {
+						"type": "string"
+					},
+					"transports": {
+						"type": "array",
+						"items": {
+							"type": "string"
+						},
+						"nullable": true
+					},
+					"backedUp": {
+						"type": "boolean"
+					},
+					"deviceType": {
+						"type": "string",
+						"enum": ["singleDevice", "multiDevice"]
+					},
+					"createdAt": {
+						"type": "string",
+						"format": "date-time",
+						"nullable": true
+					},
+					"updatedAt": {
+						"type": "string",
+						"format": "date-time",
+						"nullable": true
+					}
+				},
+				"required": ["id", "backedUp", "deviceType"]
+			},
+			"PasskeyListResponseData": {
+				"type": "object",
+				"description": "Payload returned by GET /auth/v1/passkeys.",
+				"properties": {
+					"credentials": {
+						"type": "array",
+						"items": {
+							"$ref": "#/components/schemas/PasskeyCredential"
+						}
+					}
+				},
+				"required": ["credentials"]
+			},
+			"PasskeyDeleteResponseData": {
+				"type": "object",
+				"description": "Payload returned after deleting a passkey credential.",
+				"properties": {
+					"deleted": {
+						"type": "boolean"
+					}
+				},
+				"required": ["deleted"]
+			},
+			"PasskeyChallengeRequest": {
+				"type": "object",
+				"properties": {
+					"action": {
+						"type": "string",
+						"enum": ["register", "authenticate"]
+					},
+					"login": {
+						"type": "string",
+						"nullable": true
+					},
+					"userId": {
+						"nullable": true
+					}
+				},
+				"required": ["action"]
+			},
+			"PasskeyVerifyRequest": {
+				"type": "object",
+				"properties": {
+					"expectedChallenge": {
+						"type": "string"
+					},
+					"response": {
+						"type": "object",
+						"additionalProperties": true
+					},
+					"login": {
+						"type": "string",
+						"nullable": true
+					},
+					"userId": {
+						"nullable": true
+					},
+					"userAgent": {
+						"type": "string",
+						"nullable": true
+					},
+					"domain": {
+						"type": "string",
+						"nullable": true
+					},
+					"fingerprint": {
+						"type": "string",
+						"nullable": true
+					},
+					"label": {
+						"type": "string",
+						"nullable": true
+					},
+					"browser": {
+						"type": "string",
+						"nullable": true
+					},
+					"device": {
+						"type": "string",
+						"nullable": true
+					},
+					"ip": {
+						"type": "string",
+						"nullable": true
+					},
+					"os": {
+						"type": "string",
+						"nullable": true
+					},
+					"keepSession": {
+						"nullable": true
+					}
+				},
+				"required": ["expectedChallenge", "response"]
+			},
+			"OAuthStartRequest": {
+				"type": "object",
+				"properties": {
+					"redirectUri": {
+						"type": "string",
+						"nullable": true
+					},
+					"scope": {
+						"nullable": true
+					},
+					"state": {
+						"type": "string",
+						"nullable": true
+					},
+					"extras": {
+						"type": "object",
+						"additionalProperties": true,
+						"nullable": true
+					}
+				}
+			},
+			"OAuthAuthorizeRequest": {
+				"type": "object",
+				"properties": {
+					"clientId": {
+						"type": "string"
+					},
+					"redirectUri": {
+						"type": "string"
+					},
+					"scope": {
+						"nullable": true
+					},
+					"state": {
+						"type": "string",
+						"nullable": true
+					},
+					"codeChallenge": {
+						"type": "string",
+						"nullable": true
+					},
+					"codeChallengeMethod": {
+						"type": "string",
+						"nullable": true
+					},
+					"login": {
+						"type": "string",
+						"nullable": true
+					},
+					"password": {
+						"type": "string",
+						"nullable": true
+					}
+				},
+				"required": ["clientId", "redirectUri"]
+			},
+			"OAuthTokenRequest": {
+				"type": "object",
+				"properties": {
+					"grant_type": {
+						"type": "string"
+					},
+					"code": {
+						"type": "string",
+						"nullable": true
+					},
+					"redirect_uri": {
+						"type": "string",
+						"nullable": true
+					},
+					"code_verifier": {
+						"type": "string",
+						"nullable": true
+					},
+					"refresh_token": {
+						"type": "string",
+						"nullable": true
+					},
+					"client_id": {
+						"type": "string",
+						"nullable": true
+					},
+					"client_secret": {
+						"type": "string",
+						"nullable": true
+					}
+				},
+				"required": ["grant_type"]
+			},
+			"OAuthStartResponse": {
+				"type": "object",
+				"description": "Provider-specific start payload (e.g. redirect URL, state).",
+				"additionalProperties": true
+			},
+			"OAuthCallbackResponse": {
+				"type": "object",
+				"description": "Provider-specific callback payload (may include tokens and user).",
+				"additionalProperties": true
+			},
+			"OAuthAuthorizeResponse": {
+				"type": "object",
+				"description": "Authorization code response.",
+				"properties": {
+					"code": {
+						"type": "string",
+						"description": "Authorization code."
+					},
+					"redirectUri": {
+						"type": "string",
+						"description": "Redirect URI to continue the OAuth flow."
+					},
+					"state": {
+						"type": "string",
+						"nullable": true
+					}
+				},
+				"required": ["code", "redirectUri"]
+			},
+			"OAuthTokenResponse": {
+				"type": "object",
+				"description": "Token response fields (access_token, refresh_token, etc.) as provided by the OAuth implementation.",
+				"additionalProperties": true
+			}
+		}
+	}
+}