openapi.yaml

openapi: 3.0.3
info:
  title: AuthForge API
  description: |
    Enterprise Authentication & Authorization Platform API
    
    ## Authentication
    Most endpoints require Bearer token authentication. Include the token in the Authorization header:
    ```
    Authorization: Bearer <access_token>
    ```
    
    ## Rate Limiting
    - Login: 5 attempts per 15 minutes
    - Signup: 3 attempts per hour
    - API: 100 requests per minute (authenticated)
    
    ## Error Codes
    | Code | Description |
    |------|-------------|
    | AUTH_INVALID_CREDENTIALS | Wrong email or password |
    | AUTH_TOKEN_EXPIRED | Access token expired |
    | AUTH_ACCOUNT_LOCKED | Account locked |
    | RBAC_PERMISSION_DENIED | Insufficient permissions |
    
  version: 1.0.0
  contact:
    name: AuthForge Support
    email: support@authforge.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:3000/api/v1
    description: Development server

tags:
  - name: Authentication
    description: User authentication endpoints
  - name: Users
    description: User management endpoints
  - name: Roles
    description: Role-based access control endpoints

paths:
  /auth/signup:
    post:
      tags:
        - Authentication
      summary: Register a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupRequest'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '409':
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/login:
    post:
      tags:
        - Authentication
      summary: Authenticate user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
          headers:
            Set-Cookie:
              description: HttpOnly refresh token cookie
              schema:
                type: string
        '401':
          description: Invalid credentials
        '423':
          description: Account locked

  /auth/logout:
    post:
      tags:
        - Authentication
      summary: Logout user
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                allSessions:
                  type: boolean
                  default: false
      responses:
        '200':
          description: Logged out successfully
        '401':
          $ref: '#/components/responses/Unauthorized'

  /auth/refresh:
    post:
      tags:
        - Authentication
      summary: Refresh access token
      description: Uses refresh token from HttpOnly cookie
      responses:
        '200':
          description: Token refreshed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Invalid or expired refresh token

  /auth/forgot-password:
    post:
      tags:
        - Authentication
      summary: Request password reset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
      responses:
        '200':
          description: Reset email sent (if user exists)

  /auth/reset-password:
    post:
      tags:
        - Authentication
      summary: Reset password with token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - token
                - password
              properties:
                token:
                  type: string
                password:
                  type: string
                  minLength: 12
      responses:
        '200':
          description: Password reset successful
        '401':
          description: Invalid or expired token

  /users/me:
    get:
      tags:
        - Users
      summary: Get current user profile
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    
    patch:
      tags:
        - Users
      summary: Update current user profile
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
      responses:
        '200':
          description: Profile updated
        '401':
          $ref: '#/components/responses/Unauthorized'

  /users:
    get:
      tags:
        - Users
      summary: List all users (Admin)
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: List of users
        '403':
          $ref: '#/components/responses/Forbidden'

  /users/{id}/roles:
    post:
      tags:
        - Users
      summary: Assign role to user (Admin)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - roleId
              properties:
                roleId:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Role assigned
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: User or role not found

  /roles:
    get:
      tags:
        - Roles
      summary: List all roles
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of roles
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'
    
    post:
      tags:
        - Roles
      summary: Create new role (Admin)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '201':
          description: Role created

  /health:
    get:
      tags:
        - System
      summary: Health check
      responses:
        '200':
          description: Service healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                      timestamp:
                        type: string
                        format: date-time

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    SignupRequest:
      type: object
      required:
        - email
        - password
        - firstName
        - lastName
      properties:
        email:
          type: string
          format: email
          example: user@example.com
        password:
          type: string
          minLength: 12
          description: Must contain uppercase, lowercase, number, and special character
          example: SecureP@ss123!
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe

    SignupResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            user:
              $ref: '#/components/schemas/User'
            message:
              type: string

    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string

    LoginResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            access_token:
              type: string
            token_type:
              type: string
              enum: [Bearer]
            expires_in:
              type: integer
              description: Seconds until expiration
            user:
              $ref: '#/components/schemas/User'

    TokenResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            access_token:
              type: string
            token_type:
              type: string
            expires_in:
              type: integer

    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        firstName:
          type: string
        lastName:
          type: string
        emailVerified:
          type: boolean
        status:
          type: string
          enum: [ACTIVE, PENDING, SUSPENDED, LOCKED]
        roles:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time

    UserResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/User'

    Role:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            requestId:
              type: string

  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    
    Forbidden:
      description: Permission denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    
    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'