FitTrack_GarminSync/specs/002-intialspecv2/contracts/garmin_auth_link.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "GarminSync Service API - Garmin Authentication and Linking",
    "version": "1.0.0",
    "description": "API for initiating and managing Garmin Connect authentication and account linking."
  },
  "paths": {
    "/api/garmin/auth/link": {
      "post": {
        "summary": "Initiate Garmin Connect Account Linking (Direct Email/Password)",
        "operationId": "linkGarminAccountDirect",
        "requestBody": {
          "description": "Garmin Connect credentials for direct authentication.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Garmin Connect account email."
                  },
                  "password": {
                    "type": "string",
                    "format": "password",
                    "description": "Garmin Connect account password."
                  }
                },
                "required": [
                  "email",
                  "password"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Garmin Connect account linked successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Confirmation message."
                    },
                    "user_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "ID of the user for whom the account was linked."
                    },
                    "garmin_connect_account_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "ID of the newly linked Garmin Connect account."
                    }
                  },
                  "required": [
                    "message",
                    "user_id",
                    "garmin_connect_account_id"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid credentials or account already linked."
          },
          "500": {
            "description": "Internal server error during linking process."
          }
        },
        "tags": [
          "Authentication"
        ]
      }
    }
  }
}