{
  "openapi": "3.0.3",
  "info": {
    "title": "Auth Service API",
    "version": "1.0.0",
    "description": "SSO/OIDC provider for Codevertex platform. Demo: demo@bengobox.dev / DemoUser2024!"
  },
  "servers": [
    { "url": "https://sso.codevertexafrica.com", "description": "Production (default)" },
    { "url": "https://auth.codevertex.local:4101", "description": "Local development (HTTPS)" }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
    },
    "schemas": {
      "RegisterRequest": {
        "type": "object",
        "properties": {
          "email": { "type": "string", "example": "user@example.com" },
          "password": { "type": "string", "example": "StrongPassw0rd!" },
          "tenant_slug": { "type": "string", "example": "codevertex" }
        },
        "required": ["email","password","tenant_slug"]
      },
      "LoginRequest": {
        "type": "object",
        "properties": {
          "email": { "type": "string", "example": "demo@bengobox.dev" },
          "password": { "type": "string", "example": "DemoUser2024!" },
          "tenant_slug": { "type": "string", "example": "codevertex" }
        },
        "required": ["email","password","tenant_slug"]
      },
      "PasswordResetRequest": {
        "type": "object",
        "properties": {
          "email": { "type": "string", "example": "user@example.com" },
          "tenant_slug": { "type": "string", "example": "codevertex" }
        },
        "required": ["email","tenant_slug"]
      },
      "PasswordResetConfirm": {
        "type": "object",
        "properties": {
          "token": { "type": "string", "example": "reset-token" },
          "new_password": { "type": "string", "example": "NewStrongPassw0rd!" }
        },
        "required": ["token","new_password"]
      }
    }
  },
  "security": [ { "bearerAuth": [] } ],
  "paths": {
    "/healthz": {
      "get": {
        "summary": "Health check",
        "description": "Returns service health status",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "time": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/register": { "post": { "summary": "Register", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } } }, "responses": { "201": { "description": "Created" } } } },
    "/api/v1/auth/login": {
      "post": {
        "summary": "Login",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }
        },
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/v1/auth/refresh": {
      "post": {
        "summary": "Refresh token",
        "requestBody": {
          "required": true,
          "content": { "application/json": {
            "schema": { "type": "object", "properties": { "refresh_token": { "type": "string", "example": "..." } }, "required": ["refresh_token"] }
          } }
        },
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/v1/auth/password-reset/request": { "post": { "summary": "Request password reset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordResetRequest" } } } }, "responses": { "200": { "description": "OK" } } } },
    "/api/v1/auth/password-reset/confirm": { "post": { "summary": "Confirm password reset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordResetConfirm" } } } }, "responses": { "200": { "description": "OK" } } } },
    "/api/v1/auth/me": {
      "get": { "summary": "Current user", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } }
    },
    "/api/v1/auth/logout": { "post": { "summary": "Logout", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No Content" } } } },
    "/api/v1/auth/mfa/totp/start": { "post": { "summary": "MFA TOTP start", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } } },
    "/api/v1/auth/mfa/totp/confirm": { "post": { "summary": "MFA TOTP confirm", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } } },
    "/api/v1/auth/mfa/backup-codes/regenerate": { "post": { "summary": "MFA backup codes regenerate", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } } },
    "/api/v1/auth/mfa/backup-codes/consume": { "post": { "summary": "MFA backup codes consume", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } } },
    "/api/v1/auth/oauth/google/start": { "post": { "summary": "Google OAuth start", "responses": { "200": { "description": "OK" } } } },
    "/api/v1/auth/oauth/google/callback": { "get": { "summary": "Google OAuth callback", "responses": { "200": { "description": "OK" } } } },
    "/api/v1/auth/oauth/github/start": { "post": { "summary": "GitHub OAuth start", "responses": { "200": { "description": "OK" } } } },
    "/api/v1/auth/oauth/github/callback": { "get": { "summary": "GitHub OAuth callback", "responses": { "200": { "description": "OK" } } } },
    "/api/v1/auth/oauth/microsoft/start": { "post": { "summary": "Microsoft OAuth start", "responses": { "200": { "description": "OK" } } } },
    "/api/v1/auth/oauth/microsoft/callback": { "get": { "summary": "Microsoft OAuth callback", "responses": { "200": { "description": "OK" } } } },
    "/api/v1/auth/integrations/active": {
      "get": {
        "summary": "List active integrations (public)",
        "description": "Returns platform-level and tenant-scoped integrations that are currently active. Used by auth-ui login/signup pages to render only the OAuth providers configured in auth-api.",
        "parameters": [
          { "name": "tenant_slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional tenant slug to include tenant-scoped integrations in addition to platform-level ones." },
          { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": ["oauth"] }, "description": "Filter by integration category. Currently only 'oauth' is recognised; omit to return all." }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string", "example": "google" },
                      "display_name": { "type": "string", "example": "Google OAuth" },
                      "category": { "type": "string", "example": "oauth" },
                      "logo_slug": { "type": "string", "example": "google" },
                      "brand_color": { "type": "string", "example": "#4285F4" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/.well-known/openid-configuration": {
      "get": { "summary": "OIDC discovery", "responses": { "200": { "description": "OK" } } }
    },
    "/api/v1/.well-known/jwks.json": {
      "get": { "summary": "JWKS", "responses": { "200": { "description": "OK" } } }
    },
    "/api/v1/authorize": { "get": { "summary": "Authorization endpoint (requires auth)", "security": [ { "bearerAuth": [] } ], "responses": { "302": { "description": "Redirect with code" } } } },
    "/api/v1/token": {
      "post": { "summary": "Token endpoint", "responses": { "200": { "description": "OK" } } }
    },
    "/api/v1/userinfo": {
      "get": { "summary": "Userinfo (requires auth)", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } }
    },
    "/api/v1/admin/tenants": {
      "get": { "summary": "List tenants", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } },
      "post": { "summary": "Create tenant", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created" } } }
    },
    "/api/v1/admin/clients": {
      "get": { "summary": "List clients", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } },
      "post": { "summary": "Create client", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created" } } }
    },
    "/api/v1/admin/entitlements": {
      "get": { "summary": "List entitlements", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } },
      "post": { "summary": "Upsert entitlement", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } }
    },
    "/api/v1/admin/usage/increment": {
      "post": { "summary": "Increment usage metric", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } }
    },
    "/api/v1/admin/keys/rotate": {
      "post": { "summary": "Rotate signing keys", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No Content" } } }
    }
  }
}