{
  "openapi": "3.1.0",
  "info": {
    "title": "Aetoskia Auth Server",
    "description": "\n    The Aetoskia Authentication Service.\n\n    Provides identity, access control, and JWT token issuance for the Aetoskia\n    ecosystem. Fully async, built with FastAPI and MongoDB.\n    ",
    "termsOfService": "https://aetoskia.com/terms",
    "contact": {
      "name": "Aetoskia Dev Team",
      "url": "https://dev.aetoskia.com/contact",
      "email": "dev@aetoskia.com"
    },
    "license": {
      "name": "MIT License",
      "url": "https://opensource.org/licenses/MIT"
    },
    "version": "0.0.5"
  },
  "servers": [
    {
      "url": "https://auth.aetoskia.com",
      "description": "Production Authentication Service"
    },
    {
      "url": "http://server-pi:9002",
      "description": "Internal staging environment"
    },
    {
      "url": "http://localhost:8000",
      "description": "Local development server"
    }
  ],
  "paths": {
    "/register": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Register a new user",
        "description": "Creates a new user account and returns the public user profile.",
        "operationId": "create_user_register_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicUser"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/login": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Login user",
        "description": "Authenticates a user and issues a JWT access token.",
        "operationId": "login_login_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoginResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/me": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Get current user",
        "description": "Returns the currently authenticated user's public profile.",
        "operationId": "read_users_me_me_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicUser"
                }
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ]
      }
    },
    "/logout": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Logout user",
        "description": "Stateless logout endpoint. The client must discard the JWT access token.",
        "operationId": "logout_logout_post",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogoutResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ]
      }
    },
    "/introspect": {
      "post": {
        "tags": [
          "Auth",
          "Internal"
        ],
        "summary": "Token introspection (internal)",
        "description": "Internal service-to-service endpoint for verifying JWTs. Not intended for direct client use.",
        "operationId": "introspect_introspect_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IntrospectRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntrospectResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Health Check",
        "description": "Report service health.\n\nReturns:\n    dict:\n        A simple ``{\"status\": \"ok\"}`` payload used by load balancers and\n        the container health check.",
        "operationId": "health_check_health_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "IntrospectRequest": {
        "properties": {
          "token": {
            "type": "string",
            "title": "Token",
            "description": "JWT access token to introspect",
            "examples": [
              "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
            ]
          }
        },
        "type": "object",
        "required": [
          "token"
        ],
        "title": "IntrospectRequest",
        "description": "Payload for requesting token introspection.\n\nUsed by internal services to verify the validity of a JWT and retrieve\nthe associated public user information.\n\nFields:\n    token: JWT access token to introspect.\n\nNotes:\n    - Intended for service-to-service communication.\n    - Not meant for direct end-user consumption.",
        "example": {
          "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        }
      },
      "IntrospectResponse": {
        "properties": {
          "active": {
            "type": "boolean",
            "title": "Active",
            "description": "Indicates whether the provided token is valid and active",
            "examples": [
              true,
              false
            ]
          },
          "user": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PublicUser"
              },
              {
                "type": "null"
              }
            ],
            "description": "Public user details if the token is valid; null otherwise"
          }
        },
        "type": "object",
        "required": [
          "active"
        ],
        "title": "IntrospectResponse",
        "description": "Result of a token introspection operation.\n\nThis model communicates whether a JWT is valid and, if so, provides\nthe associated public user information.\n\nFields:\n    active: Indicates whether the token is valid and active.\n    user: Public user details if the token is valid; otherwise null.\n\nNotes:\n    - This model is designed to avoid raising exceptions.\n    - All introspection outcomes are represented as data.",
        "example": {
          "active": true,
          "user": {
            "email": "tester@example.com",
            "is_active": true,
            "username": "tester"
          }
        }
      },
      "LoginRequest": {
        "properties": {
          "password": {
            "type": "string",
            "minLength": 6,
            "title": "Password",
            "description": "User password (minimum 6 characters). Stored only as a hash.",
            "examples": [
              "SuperSecure123"
            ]
          },
          "username": {
            "type": "string",
            "maxLength": 50,
            "minLength": 3,
            "title": "Username",
            "description": "Unique username used for authentication and display",
            "examples": [
              "tester"
            ]
          },
          "email": {
            "anyOf": [
              {
                "type": "string",
                "format": "email"
              },
              {
                "type": "null"
              }
            ],
            "title": "Email",
            "description": "Primary email address associated with the account",
            "examples": [
              "tester@example.com"
            ]
          }
        },
        "type": "object",
        "required": [
          "password",
          "username"
        ],
        "title": "LoginRequest",
        "description": "Payload for authenticating a user and issuing a JWT.\n\nThis model is used to verify user credentials and request an access token.\n\nFields:\n    username: Username identifier.\n    password: Plain-text password to be verified.\n\nNotes:\n    - Successful authentication results in a LoginResponse.\n    - Failed authentication raises an AuthError.",
        "example": {
          "password": "SuperSecure123",
          "username": "tester"
        }
      },
      "LoginResponse": {
        "properties": {
          "access_token": {
            "type": "string",
            "title": "Access Token",
            "description": "JWT access token to be used for authenticated requests",
            "examples": [
              "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
            ]
          },
          "user": {
            "$ref": "#/components/schemas/PublicUser",
            "description": "Authenticated user's public profile"
          }
        },
        "type": "object",
        "required": [
          "access_token",
          "user"
        ],
        "title": "LoginResponse",
        "description": "Response returned after successful authentication.\n\nContains the issued JWT access token and the authenticated user's\npublic profile.\n\nFields:\n    access_token: JWT access token for authenticated requests.\n    user: Public profile of the authenticated user.\n\nNotes:\n    - The token is stateless and must be stored client-side.\n    - Token expiration and validation are handled elsewhere.",
        "example": {
          "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
          "user": {
            "email": "tester@example.com",
            "is_active": true,
            "username": "tester"
          }
        }
      },
      "LogoutResponse": {
        "properties": {
          "message": {
            "type": "string",
            "title": "Message",
            "description": "Human-readable logout confirmation message",
            "examples": [
              "Successfully logged out"
            ]
          }
        },
        "type": "object",
        "required": [
          "message"
        ],
        "title": "LogoutResponse",
        "description": "Response returned after a logout operation.\n\nSince logout is stateless, this response serves only as a confirmation\nmessage instructing the client to discard its token.\n\nFields:\n    message: Human-readable logout confirmation.",
        "example": {
          "message": "Successfully logged out"
        }
      },
      "PublicUser": {
        "properties": {
          "is_active": {
            "type": "boolean",
            "title": "Is Active",
            "description": "Indicates whether the account is active and allowed to authenticate",
            "default": true,
            "examples": [
              true
            ]
          },
          "username": {
            "type": "string",
            "maxLength": 50,
            "minLength": 3,
            "title": "Username",
            "description": "Unique username used for authentication and display",
            "examples": [
              "tester"
            ]
          },
          "email": {
            "anyOf": [
              {
                "type": "string",
                "format": "email"
              },
              {
                "type": "null"
              }
            ],
            "title": "Email",
            "description": "Primary email address associated with the account",
            "examples": [
              "tester@example.com"
            ]
          }
        },
        "type": "object",
        "required": [
          "username"
        ],
        "title": "PublicUser",
        "description": "Public-facing user representation returned by authentication APIs.\n\nThis model represents a user profile that is safe to expose outside\nthe authentication system.\n\nFields:\n    username: Unique username identifier.\n    email: User's email address.\n    is_active: Whether the user account is active.\n\nNotes:\n    - Contains no sensitive data.\n    - Can be constructed from persistence models via `from_attributes`.",
        "example": {
          "email": "tester@example.com",
          "is_active": true,
          "username": "tester"
        }
      },
      "RegisterRequest": {
        "properties": {
          "password": {
            "type": "string",
            "minLength": 6,
            "title": "Password",
            "description": "User password (minimum 6 characters). Stored only as a hash.",
            "examples": [
              "SuperSecure123"
            ]
          },
          "username": {
            "type": "string",
            "maxLength": 50,
            "minLength": 3,
            "title": "Username",
            "description": "Unique username used for authentication and display",
            "examples": [
              "tester"
            ]
          },
          "email": {
            "anyOf": [
              {
                "type": "string",
                "format": "email"
              },
              {
                "type": "null"
              }
            ],
            "title": "Email",
            "description": "Primary email address associated with the account",
            "examples": [
              "tester@example.com"
            ]
          }
        },
        "type": "object",
        "required": [
          "password",
          "username"
        ],
        "title": "RegisterRequest",
        "description": "Payload for registering a new user account.\n\nThis model contains the minimum required identity and credential\ninformation to create a new user.\n\nFields:\n    username: Unique username identifier.\n    email: User's email address.\n    password: Plain-text password (to be hashed by the repository layer).\n\nNotes:\n    - Validation and normalization handled by mixins.\n    - This model is never returned in responses.",
        "example": {
          "email": "tester@example.com",
          "password": "SuperSecure123",
          "username": "tester"
        }
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    },
    "securitySchemes": {
      "HTTPBearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "tags": [
    {
      "name": "Auth",
      "description": "Login, registration, token issuance, refresh, and identity operations."
    },
    {
      "name": "Health",
      "description": "Service health and diagnostics."
    }
  ]
}