openapi.yaml

openapi: 3.1.0
info:
  title: Open Insurance API
  version: 0.1.0
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  description: |
    HTTP API exposed via the Kong gateway. Paths are prefixed by service name
    (`/identity`, `/application`, `/storage`). Internal service URLs are not
    part of the public contract.

    gRPC definitions live under `proto/` and are documented separately.

servers:
  - url: http://localhost:8000
    description: Kong gateway (local Docker deploy)

tags:
  - name: Identity
    description: Authentication and identity management
  - name: Application
    description: Core insurance business logic
  - name: Storage
    description: Documents, objects, and metadata
  - name: Health
    description: Liveness and readiness probes

paths:
  /identity/auth/login:
    post:
      tags: [Identity]
      summary: Login with email and password
      description: |
        Authenticates a user and returns a short-lived JWT access token.
        Passwords are verified against Argon2id hashes stored in PostgreSQL.
      operationId: identityLogin
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            example:
              email: user@example.com
              password: secret123
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '400':
          description: Invalid request body or missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidBody:
                  value:
                    error: invalid request body
                invalidRequest:
                  value:
                    error: invalid request
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: invalid credentials
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /identity/healthz:
    get:
      tags: [Health, Identity]
      summary: Identity liveness check
      operationId: identityHealthz
      security: []
      responses:
        '200':
          description: Service is alive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'

  /identity/readyz:
    get:
      tags: [Health, Identity]
      summary: Identity readiness check
      operationId: identityReadyz
      security: []
      responses:
        '200':
          description: Service is ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'

  /application/healthz:
    get:
      tags: [Health, Application]
      summary: Application liveness check
      operationId: applicationHealthz
      security: []
      responses:
        '200':
          description: Service is alive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'

  /application/readyz:
    get:
      tags: [Health, Application]
      summary: Application readiness check
      operationId: applicationReadyz
      security: []
      responses:
        '200':
          description: Service is ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'

  /storage/healthz:
    get:
      tags: [Health, Storage]
      summary: Storage liveness check
      operationId: storageHealthz
      security: []
      responses:
        '200':
          description: Service is alive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'

  /storage/readyz:
    get:
      tags: [Health, Storage]
      summary: Storage readiness check
      operationId: storageReadyz
      security: []
      responses:
        '200':
          description: Service is ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'

  /identity/auth/me:
    get:
      tags: [Identity]
      summary: Current authenticated user
      operationId: identityMe
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Current user profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /identity/users:
    get:
      tags: [Identity]
      summary: List users
      operationId: identityListUsers
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Paginated user list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags: [Identity]
      summary: Create user
      operationId: identityCreateUser
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /identity/users/{id}:
    get:
      tags: [Identity]
      summary: Get user by ID
      operationId: identityGetUser
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags: [Identity]
      summary: Update user
      operationId: identityUpdateUser
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: Updated user profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Identity]
      summary: Delete user
      operationId: identityDeleteUser
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: User deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  responses:
    MethodNotAllowed:
      description: HTTP method not supported for this route
    Unauthorized:
      description: Missing or invalid bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT issued by `POST /identity/auth/login`. Required for protected identity
        routes such as `/identity/users` and `/identity/auth/me`.

  schemas:
    LoginRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
          example: user@example.com
        password:
          type: string
          format: password
          minLength: 1

    LoginResponse:
      type: object
      required: [access_token, token_type, expires_in]
      properties:
        access_token:
          type: string
          description: Signed JWT access token
        token_type:
          type: string
          enum: [Bearer]
        expires_in:
          type: integer
          format: int64
          description: Token lifetime in seconds

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string

    HealthStatus:
      type: object
      required: [service, status, timestamp]
      properties:
        service:
          type: string
          example: identity
        status:
          type: string
          example: ok
        timestamp:
          type: string
          format: date-time

    UserProfile:
      type: object
      required: [id, email, roles, created_at, updated_at]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        roles:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateUserRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
        roles:
          type: array
          items:
            type: string

    UpdateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
        roles:
          type: array
          items:
            type: string

    UserListResponse:
      type: object
      required: [users, total, limit, offset]
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserProfile'
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer