563 lines
17 KiB
JSON
563 lines
17 KiB
JSON
{
|
|
"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."
|
|
}
|
|
]
|
|
} |