openapi: 3.0.3 info: title: Insforge Authentication API version: 2.0.0 description: Authentication endpoints with separated auth and profile tables paths: /api/auth/users: post: summary: Register new user description: Creates a new user account tags: - Client requestBody: required: true content: application/json: schema: type: object required: - email - password properties: email: type: string format: email example: user@example.com password: type: string minLength: 8 example: securepassword123 name: type: string example: John Doe responses: '201': description: User created successfully content: application/json: schema: type: object properties: user: type: object properties: id: type: string format: uuid email: type: string name: type: string emailVerified: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time accessToken: type: string description: JWT authentication token '400': description: Invalid request '409': description: User already exists get: summary: List all users (admin only) description: Returns paginated list of users tags: - Admin security: - bearerAuth: [] parameters: - name: page in: query schema: type: integer default: 1 - name: limit in: query schema: type: integer default: 10 - name: search in: query schema: type: string - name: role in: query schema: type: string enum: - user - admin responses: '200': description: List of users content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string email: type: string name: type: string role: type: string created_at: type: string format: date-time pagination: type: object properties: offset: type: integer limit: type: integer total: type: integer '401': description: Unauthorized '403': description: Forbidden - Admin only delete: summary: Delete users (admin only) description: Delete multiple users by their IDs tags: - Admin security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: userIds: type: array items: type: string required: - userIds responses: '200': description: Users deleted successfully content: application/json: schema: type: object properties: message: type: string deletedCount: type: integer '401': description: Unauthorized '403': description: Forbidden - Admin only /api/auth/sessions: post: summary: User login description: Authenticates user and returns access token tags: - Client requestBody: required: true content: application/json: schema: type: object required: - email - password properties: email: type: string format: email password: type: string responses: '200': description: Login successful content: application/json: schema: type: object properties: user: type: object properties: id: type: string format: uuid email: type: string name: type: string emailVerified: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time accessToken: type: string '401': description: Invalid credentials /api/auth/sessions/current: get: summary: Get current user description: Returns the currently authenticated user tags: - Client security: - bearerAuth: [] responses: '200': description: Current user info content: application/json: schema: type: object properties: user: type: object properties: id: type: string email: type: string name: type: string role: type: string '401': description: Unauthorized /api/auth/admin/sessions: post: summary: Admin login description: Authenticates admin user for dashboard access tags: - Admin requestBody: required: true content: application/json: schema: type: object required: - email - password properties: email: type: string format: email password: type: string responses: '200': description: Admin login successful content: application/json: schema: type: object properties: accessToken: type: string user: type: object properties: id: type: string email: type: string name: type: string role: type: string enum: - admin '401': description: Invalid credentials '403': description: User is not an admin /api/auth/admin/sessions/exchange: post: summary: Exchange cloud provider authorization code for admin session description: >- Verifies an authorization code/JWT from from Insforge Cloud platform and issues an internal admin session token with project_admin role tags: - Admin requestBody: required: true content: application/json: schema: type: object required: - code properties: code: type: string description: Authorization code or JWT from the Insforge example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... responses: '200': description: Cloud authorization verified, admin session created content: application/json: schema: type: object properties: accessToken: type: string description: Internal JWT for admin authentication user: type: object properties: id: type: string format: uuid email: type: string name: type: string example: Administrator emailVerified: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time '400': description: Invalid authorization code or JWT verification failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /api/auth/tokens/anon: post: summary: Generate anonymous token description: >- Generate a non-expiring anonymous JWT token for public API access (admin only) tags: - Client security: - bearerAuth: [] responses: '200': description: Anonymous token generated successfully content: application/json: schema: type: object properties: accessToken: type: string description: Non-expiring anonymous JWT token example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... message: type: string description: Success message example: Anonymous token generated successfully (never expires) '401': description: Unauthorized - requires authentication '403': description: Forbidden - admin access required /api/auth/oauth/google: get: summary: Initiate Google OAuth flow tags: - Client parameters: - name: redirect_uri in: query schema: type: string format: uri description: URL to redirect after authentication responses: '302': description: Redirect to Google OAuth '500': description: OAuth not configured /api/auth/oauth/github: get: summary: Initiate GitHub OAuth flow tags: - Client parameters: - name: redirect_uri in: query schema: type: string format: uri description: URL to redirect after authentication responses: '302': description: Redirect to GitHub OAuth '500': description: OAuth not configured /api/auth/oauth/shared/callback: get: summary: Shared OAuth callback handler description: Handles OAuth callbacks from all providers tags: - Client parameters: - name: code in: query schema: type: string description: Authorization code from OAuth provider - name: state in: query schema: type: string description: JWT encoded state with provider and redirect URL - name: token in: query schema: type: string description: Direct ID token (for Google) responses: '302': description: Redirect with access token and user info in query params headers: Location: schema: type: string format: uri /api/auth/oauth/{provider}/callback: get: summary: Provider-specific OAuth callback description: Alternative callback endpoint for specific providers tags: - Client parameters: - name: provider in: path required: true schema: type: string enum: - google - github - name: code in: query schema: type: string - name: state in: query schema: type: string - name: token in: query schema: type: string responses: '302': description: Redirect with access token components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT apiKey: type: apiKey in: header name: x-api-key schemas: AuthRecord: type: object properties: id: type: string format: uuid email: type: string format: email passwordHash: type: string description: SHA256 hash of password createdAt: type: string format: date-time updatedAt: type: string format: date-time ProfileRecord: type: object properties: id: type: string format: uuid authId: type: string format: uuid description: Foreign key to auth table name: type: string avatar_url: type: string nullable: true bio: type: string nullable: true metadata: type: object description: JSONB field for flexible data createdAt: type: string format: date-time updatedAt: type: string format: date-time ErrorResponse: type: object required: - error - message - statusCode properties: error: type: string description: Error code for programmatic handling example: VALIDATION_ERROR message: type: string description: Human-readable error message example: Email is already in use statusCode: type: integer description: HTTP status code example: 400 nextActions: type: string description: Suggested action to resolve the error example: Please use a different email address