{
  "openapi": "3.1.0",
  "info": {
    "title": "Authula API",
    "description": "Authula API - An open-source authentication solution that scales with you.",
    "version": "0.1.0"
  },
  "servers": [{ "url": "http://localhost:8080" }],
  "paths": {
    "/api/auth/.well-known/jwks.json": {
      "get": {
        "tags": ["JWT Plugin"],
        "summary": "Get JWKS",
        "description": "Returns the JSON Web Key Set (JWKS) containing the public keys used to verify JWT signatures.",
        "operationId": "getJWKS",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WellKnownJWKSResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/email-password/change-password": {
      "post": {
        "tags": ["Email Password Plugin"],
        "summary": "Change password",
        "description": "Changes the user's password using a reset token",
        "operationId": "changePassword",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChangePasswordResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/email-password/request-email-change": {
      "post": {
        "tags": ["Email Password Plugin"],
        "summary": "Request email change",
        "description": "Requests to change the authenticated user's email address",
        "operationId": "requestEmailChange",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestEmailChangeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ChangeEmailResponse" }
              }
            }
          }
        }
      }
    },
    "/api/auth/email-password/request-password-reset": {
      "post": {
        "tags": ["Email Password Plugin"],
        "summary": "Request password reset",
        "description": "Requests a password reset link to be sent to the user's email",
        "operationId": "requestPasswordReset",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestPasswordResetRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChangePasswordResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/email-password/send-email-verification": {
      "post": {
        "tags": ["Email Password Plugin"],
        "summary": "Send email verification",
        "description": "Sends a verification email to the authenticated user",
        "operationId": "sendEmailVerification",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendEmailVerificationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChangePasswordResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/email-password/sign-in": {
      "post": {
        "tags": ["Email Password Plugin"],
        "summary": "Sign in",
        "description": "Authenticates a user with email and password",
        "operationId": "signIn",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SignInRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SignInResponse" }
              }
            }
          }
        }
      }
    },
    "/api/auth/email-password/sign-up": {
      "post": {
        "tags": ["Email Password Plugin"],
        "summary": "Register new user",
        "description": "Registers a new user with email and password",
        "operationId": "signUp",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SignUpRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SignUpResponse" }
              }
            }
          }
        }
      }
    },
    "/api/auth/email-password/verify-email": {
      "get": {
        "tags": ["Email Password Plugin"],
        "summary": "Verify email",
        "description": "Verifies an email address or processes a password reset token using a verification token",
        "operationId": "verifyEmail",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChangePasswordResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/magic-link/exchange": {
      "post": {
        "tags": ["Magic Link Plugin"],
        "summary": "Exchange magic link token for session",
        "description": "Exchanges a verified magic link token for an authenticated user session.",
        "operationId": "exchange",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MagicLinkExchangeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MagicLinkExchangeResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/magic-link/sign-in": {
      "post": {
        "tags": ["Magic Link Plugin"],
        "summary": "Sign in with magic link",
        "description": "Sends a magic link to the given email address if an account exists. Optionally creates a new account if sign-up is enabled.",
        "operationId": "signIn",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MagicLinkSignInRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MagicLinkSignInResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/magic-link/verify": {
      "get": {
        "tags": ["Magic Link Plugin"],
        "summary": "Verify magic link token",
        "description": "Verifies a magic link token. If a callback_url is provided and trusted, redirects the user with an exchange token appended. Otherwise returns the exchange token in the JSON response.",
        "operationId": "verify",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "callback_url",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MagicLinkVerifyResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/oauth2/authorize/{provider}": {
      "get": {
        "tags": ["OAuth2 Plugin"],
        "summary": "Authorize with OAuth2 provider",
        "description": "Initiates the OAuth2 authorization flow with the specified provider. Returns the provider's authorization URL to redirect the user to.",
        "operationId": "authorize",
        "parameters": [
          {
            "name": "redirect_to",
            "in": "query",
            "schema": { "type": "string" }
          },
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AuthorizeResponse" }
              }
            }
          }
        }
      }
    },
    "/api/auth/oauth2/callback/{provider}": {
      "get": {
        "tags": ["OAuth2 Plugin"],
        "summary": "OAuth2 callback",
        "description": "Handles the OAuth2 callback from the provider. Exchanges the authorization code for tokens, creates or links a user account, and returns the authenticated user and session.",
        "operationId": "callback",
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          },
          { "name": "error", "in": "query", "schema": { "type": "string" } },
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CallbackResponse" }
              }
            }
          }
        }
      }
    },
    "/api/auth/token/refresh": {
      "post": {
        "tags": ["JWT Plugin"],
        "summary": "Refresh JWT token",
        "description": "Exchanges a valid refresh token for a new access token and refresh token pair.",
        "operationId": "refreshToken",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefreshTokenResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/totp/disable": {
      "post": {
        "tags": ["TOTP Plugin"],
        "summary": "Disable TOTP",
        "description": "Disables TOTP two-factor authentication for the authenticated user.",
        "operationId": "disableTotp",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DisableResponse" }
              }
            }
          }
        }
      }
    },
    "/api/auth/totp/enable": {
      "post": {
        "tags": ["TOTP Plugin"],
        "summary": "Enable TOTP",
        "description": "Enables TOTP two-factor authentication for the authenticated user. Returns the TOTP URI and backup codes.",
        "operationId": "enableTotp",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EnableResponse" }
              }
            }
          }
        }
      }
    },
    "/api/auth/totp/generate-backup-codes": {
      "post": {
        "tags": ["TOTP Plugin"],
        "summary": "Generate backup codes",
        "description": "Generates a new set of backup codes for the authenticated user. Previous backup codes are invalidated.",
        "operationId": "generateTotpBackupCodes",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerateBackupCodesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/totp/get-uri": {
      "get": {
        "tags": ["TOTP Plugin"],
        "summary": "Get TOTP URI",
        "description": "Returns the current TOTP URI for the authenticated user's authenticator app configuration.",
        "operationId": "getTotpURI",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GetTOTPURIResponse" }
              }
            }
          }
        }
      }
    },
    "/api/auth/totp/verify": {
      "post": {
        "tags": ["TOTP Plugin"],
        "summary": "Verify TOTP code",
        "description": "Verifies a TOTP code from the authenticator app and completes authentication. Requires a pending TOTP cookie set during sign-in.",
        "operationId": "verifyTotp",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/VerifyTOTPRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VerifyTOTPResponse" }
              }
            }
          }
        }
      }
    },
    "/api/auth/totp/verify-backup-code": {
      "post": {
        "tags": ["TOTP Plugin"],
        "summary": "Verify backup code",
        "description": "Verifies a backup code as an alternative to TOTP verification. Completes authentication if the code is valid.",
        "operationId": "verifyTotpBackupCode",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyBackupCodeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyBackupCodeResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AuthorizeResponse": {
        "properties": { "auth_url": { "type": "string" } },
        "required": ["auth_url"],
        "type": "object"
      },
      "CallbackResponse": {
        "properties": {
          "session": { "$ref": "#/components/schemas/Session" },
          "user": { "$ref": "#/components/schemas/User" }
        },
        "required": ["user", "session"],
        "type": "object"
      },
      "ChangeEmailResponse": {
        "properties": { "message": { "type": "string" } },
        "required": ["message"],
        "type": "object"
      },
      "ChangePasswordRequest": {
        "properties": {
          "password": { "type": "string" },
          "token": { "type": "string" }
        },
        "required": ["token", "password"],
        "type": "object"
      },
      "ChangePasswordResponse": {
        "properties": { "message": { "type": "string" } },
        "required": ["message"],
        "type": "object"
      },
      "DisableResponse": {
        "properties": { "message": { "type": "string" } },
        "required": ["message"],
        "type": "object"
      },
      "EnableResponse": {
        "properties": {
          "backup_codes": { "items": { "type": "string" }, "type": "array" },
          "totp_uri": { "type": "string" }
        },
        "required": ["totp_uri", "backup_codes"],
        "type": "object"
      },
      "GenerateBackupCodesResponse": {
        "properties": {
          "backup_codes": { "items": { "type": "string" }, "type": "array" }
        },
        "required": ["backup_codes"],
        "type": "object"
      },
      "GetTOTPURIResponse": {
        "properties": { "totp_uri": { "type": "string" } },
        "required": ["totp_uri"],
        "type": "object"
      },
      "JWK": {
        "properties": {
          "alg": { "type": "string" },
          "crv": { "type": "string" },
          "e": { "type": "string" },
          "kid": { "type": "string" },
          "kty": { "type": "string" },
          "n": { "type": "string" },
          "use": { "type": "string" },
          "x": { "type": "string" }
        },
        "required": ["kty"],
        "type": "object"
      },
      "MagicLinkExchangeRequest": {
        "properties": { "token": { "type": "string" } },
        "required": ["token"],
        "type": "object"
      },
      "MagicLinkExchangeResponse": {
        "properties": {
          "session": { "$ref": "#/components/schemas/Session" },
          "user": { "$ref": "#/components/schemas/User" }
        },
        "required": ["user", "session"],
        "type": "object"
      },
      "MagicLinkSignInRequest": {
        "properties": {
          "callback_url": { "type": ["null", "string"] },
          "email": { "type": "string" },
          "name": { "type": ["null", "string"] }
        },
        "required": ["email"],
        "type": "object"
      },
      "MagicLinkSignInResponse": {
        "properties": { "message": { "type": "string" } },
        "required": ["message"],
        "type": "object"
      },
      "MagicLinkVerifyResponse": {
        "properties": {
          "message": { "type": "string" },
          "token": { "type": "string" }
        },
        "required": ["message"],
        "type": "object"
      },
      "RefreshTokenRequest": {
        "properties": { "refresh_token": { "type": "string" } },
        "required": ["refresh_token"],
        "type": "object"
      },
      "RefreshTokenResponse": {
        "properties": {
          "access_token": { "type": "string" },
          "refresh_token": { "type": "string" }
        },
        "required": ["access_token", "refresh_token"],
        "type": "object"
      },
      "RequestEmailChangeRequest": {
        "properties": {
          "callback_url": { "type": ["null", "string"] },
          "new_email": { "type": "string" }
        },
        "required": ["new_email"],
        "type": "object"
      },
      "RequestPasswordResetRequest": {
        "properties": {
          "callback_url": { "type": ["null", "string"] },
          "email": { "type": "string" }
        },
        "required": ["email"],
        "type": "object"
      },
      "SendEmailVerificationRequest": {
        "properties": { "callback_url": { "type": ["null", "string"] } },
        "type": "object"
      },
      "Session": {
        "properties": {
          "created_at": { "format": "date-time", "type": "string" },
          "expires_at": { "format": "date-time", "type": "string" },
          "id": { "type": "string" },
          "ip_address": { "type": ["null", "string"] },
          "token": { "type": "string" },
          "updated_at": { "format": "date-time", "type": "string" },
          "user_agent": { "type": ["null", "string"] },
          "user_id": { "type": "string" }
        },
        "type": "object"
      },
      "SignInRequest": {
        "properties": {
          "callback_url": { "type": ["null", "string"] },
          "email": { "type": "string" },
          "password": { "type": "string" }
        },
        "required": ["email", "password"],
        "type": "object"
      },
      "SignInResponse": {
        "properties": {
          "session": { "$ref": "#/components/schemas/Session" },
          "user": { "$ref": "#/components/schemas/User" }
        },
        "required": ["user", "session"],
        "type": "object"
      },
      "SignUpRequest": {
        "properties": {
          "callback_url": { "type": ["null", "string"] },
          "email": { "type": "string" },
          "image": { "type": ["null", "string"] },
          "metadata": {
            "additionalProperties": {},
            "type": ["object", "null"]
          },
          "name": { "type": "string" },
          "password": { "type": "string" }
        },
        "required": ["name", "email", "password"],
        "type": "object"
      },
      "SignUpResponse": {
        "properties": {
          "session": { "$ref": "#/components/schemas/Session" },
          "user": { "$ref": "#/components/schemas/User" }
        },
        "required": ["user", "session"],
        "type": "object"
      },
      "User": {
        "properties": {
          "created_at": { "format": "date-time", "type": "string" },
          "email": { "type": "string" },
          "email_verified": { "type": "boolean" },
          "id": { "type": "string" },
          "image": { "type": ["null", "string"] },
          "metadata": {
            "additionalProperties": {},
            "type": ["object", "null"]
          },
          "name": { "type": "string" },
          "updated_at": { "format": "date-time", "type": "string" }
        },
        "type": "object"
      },
      "VerifyBackupCodeRequest": {
        "properties": {
          "code": { "type": "string" },
          "trust_device": { "type": "boolean" }
        },
        "required": ["code"],
        "type": "object"
      },
      "VerifyBackupCodeResponse": {
        "properties": {
          "session": { "$ref": "#/components/schemas/Session" },
          "user": { "$ref": "#/components/schemas/User" }
        },
        "required": ["user", "session"],
        "type": "object"
      },
      "VerifyTOTPRequest": {
        "properties": {
          "code": { "type": "string" },
          "trust_device": { "type": "boolean" }
        },
        "required": ["code"],
        "type": "object"
      },
      "VerifyTOTPResponse": {
        "properties": {
          "session": { "$ref": "#/components/schemas/Session" },
          "user": { "$ref": "#/components/schemas/User" }
        },
        "required": ["user", "session"],
        "type": "object"
      },
      "WellKnownJWKSResponse": {
        "properties": {
          "keys": {
            "items": { "$ref": "#/components/schemas/JWK" },
            "type": "array"
          }
        },
        "required": ["keys"],
        "type": "object"
      }
    }
  }
}