@friggframework/core 2.0.0--canary.548.c8ae0ca.0 → 2.0.0--canary.545.c40eca4.0

package/openapi/openapi-v1.yaml

@@ -0,0 +1,1360 @@
+openapi: 3.0.3
+info:
+    title: Frigg Framework API (v1)
+    version: 1.0.0
+    description: |
+        Enterprise-grade serverless integration framework API for managing integrations,
+        entities, credentials, and proxying requests to external systems.
+
+        ## API Version: v1 (Legacy)
+
+        This is the **v1 API** which provides backwards compatibility with existing integrations.
+        For new implementations, consider using the [v2 API](/api/v2/docs) which offers cleaner
+        response structures with better separation of concerns.
+
+        ### Key v1 Behaviors
+
+        - `GET /api/integrations` returns a **combined response** with entities and integrations
+        - Entity options and authorized entities are nested under the `entities` key
+        - This format is maintained for backwards compatibility
+
+        ## Overview
+        The Frigg Framework enables direct/native integrations between products and external
+        software partners through a standardized API that handles authentication, authorization,
+        and data synchronization.
+
+        ## Key Concepts
+        - **Entities**: Connected accounts representing external integrations (e.g., a HubSpot account)
+        - **Credentials**: Authentication data for external systems (OAuth tokens, API keys)
+        - **Integrations**: Configured bidirectional sync relationships between entities
+        - **Proxy**: Secure API forwarding to external systems using stored credentials
+
+        ## Authentication
+        All API endpoints require Bearer token authentication unless otherwise noted.
+    contact:
+        name: Frigg Framework
+        url: https://friggframework.org
+    license:
+        name: MIT
+
+servers:
+    - url: http://localhost:3000
+      description: Local development server
+    - url: https://api.{stage}.friggframework.org
+      description: Production environments
+      variables:
+          stage:
+              default: prod
+              enum:
+                  - dev
+                  - staging
+                  - prod
+
+security:
+    - bearerAuth: []
+
+tags:
+    - name: Integrations
+      description: |
+          Integration management endpoints.
+
+          **v1 Note**: `GET /api/integrations` returns a combined response including
+          entities and integration options for backwards compatibility.
+    - name: Authorization
+      description: OAuth and authentication flows for connecting external systems
+    - name: Entities
+      description: Connected accounts and entity management
+    - name: Credentials
+      description: Credential management and reauthorization
+    - name: Health
+      description: Service health and readiness checks
+
+paths:
+    # Integration Endpoints (v1 combined response)
+    /api/integrations:
+        get:
+            tags:
+                - Integrations
+            summary: List integrations with entities (v1 combined response)
+            description: |
+                Retrieve user's integrations along with available integration options and authorized entities.
+
+                **v1 Response Format**: This endpoint returns a combined response for backwards compatibility:
+                - `entities.options`: Available integration types that can be connected
+                - `entities.authorized`: User's connected entities (accounts)
+                - `integrations`: User's active integrations
+
+                **Migration Note**: In v2, these are split into separate endpoints:
+                - `GET /api/v2/integrations` - Returns only integrations
+                - `GET /api/v2/integrations/options` - Returns available options
+                - `GET /api/v2/entities` - Returns authorized entities
+            operationId: listIntegrationsV1
+            responses:
+                '200':
+                    description: Combined integrations and entities response
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ListIntegrationsV1Response'
+                            example:
+                                entities:
+                                    options:
+                                        - type: hubspot
+                                          name: HubSpot
+                                          description: HubSpot CRM integration
+                                          hasAuth: true
+                                        - type: salesforce
+                                          name: Salesforce
+                                          description: Salesforce CRM integration
+                                          hasAuth: true
+                                    authorized:
+                                        - id: entity-123
+                                          type: hubspot
+                                          name: My HubSpot Account
+                                          externalId: hub-12345
+                                          credential_id: cred-abc
+                                integrations:
+                                    - id: int-456
+                                      userId: user-789
+                                      config:
+                                          type: hubspot-salesforce
+                                      status: ENABLED
+                                      entities:
+                                          - entity-123
+                                          - entity-456
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+
+        post:
+            tags:
+                - Integrations
+            summary: Create integration
+            description: Create a new integration between two or more entities
+            operationId: createIntegration
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/CreateIntegrationRequest'
+            responses:
+                '201':
+                    description: Integration created successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/Integration'
+                '400':
+                    $ref: '#/components/responses/BadRequest'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+
+    /api/integrations/options:
+        get:
+            tags:
+                - Integrations
+            summary: List available integration types
+            description: Get available integration types that can be configured
+            operationId: listIntegrationOptions
+            responses:
+                '200':
+                    description: List of available integration types
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ListIntegrationOptionsResponse'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+
+    /api/integrations/{integrationId}:
+        get:
+            tags:
+                - Integrations
+            summary: Get integration
+            description: Retrieve detailed information about a specific integration
+            operationId: getIntegration
+            parameters:
+                - $ref: '#/components/parameters/IntegrationId'
+            responses:
+                '200':
+                    description: Integration retrieved successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/Integration'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+
+        patch:
+            tags:
+                - Integrations
+            summary: Update integration
+            description: Update integration configuration
+            operationId: updateIntegration
+            parameters:
+                - $ref: '#/components/parameters/IntegrationId'
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/UpdateIntegrationRequest'
+            responses:
+                '200':
+                    description: Integration updated successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/Integration'
+                '400':
+                    $ref: '#/components/responses/BadRequest'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+
+        delete:
+            tags:
+                - Integrations
+            summary: Delete integration
+            description: Delete an integration (entities and credentials remain)
+            operationId: deleteIntegration
+            parameters:
+                - $ref: '#/components/parameters/IntegrationId'
+            responses:
+                '200':
+                    description: Integration deleted successfully
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    success:
+                                        type: boolean
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+
+    # Authorization Endpoints
+    /api/authorize:
+        get:
+            tags:
+                - Authorization
+            summary: Get authorization requirements
+            description: |
+                Retrieve the authentication requirements for a given entity type and step.
+                Used to start or continue a multi-step authorization flow.
+            operationId: getAuthorizationRequirements
+            parameters:
+                - name: entityType
+                  in: query
+                  required: true
+                  schema:
+                      type: string
+                  description: Module/entity type to authorize (e.g., 'hubspot', 'salesforce')
+                - name: step
+                  in: query
+                  schema:
+                      type: integer
+                      minimum: 1
+                      default: 1
+                  description: Current step number (for multi-step flows)
+                - name: sessionId
+                  in: query
+                  schema:
+                      type: string
+                  description: Session ID from previous step (required for step > 1)
+            responses:
+                '200':
+                    description: Authorization requirements retrieved successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/AuthorizationRequirements'
+                '400':
+                    $ref: '#/components/responses/BadRequest'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+
+        post:
+            tags:
+                - Authorization
+            summary: Submit authorization data
+            description: |
+                Submit authentication data to authorize an entity. This may complete the
+                authorization or return next step requirements for multi-step flows.
+            operationId: submitAuthorization
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/AuthorizationRequest'
+            responses:
+                '200':
+                    description: Authorization completed or next step returned
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/AuthorizationResponse'
+                '400':
+                    $ref: '#/components/responses/BadRequest'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '422':
+                    $ref: '#/components/responses/ValidationError'
+
+    # Entity Endpoints
+    /api/entities:
+        get:
+            tags:
+                - Entities
+            summary: List user's entities
+            description: Retrieve all entities owned by the authenticated user
+            operationId: listEntities
+            responses:
+                '200':
+                    description: List of entities retrieved successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ListEntitiesResponse'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+
+        post:
+            tags:
+                - Entities
+            summary: Create entity from credential
+            description: Create a new entity linked to an existing credential
+            operationId: createEntity
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/CreateEntityRequest'
+            responses:
+                '201':
+                    description: Entity created successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/CreateEntityResponse'
+                '400':
+                    $ref: '#/components/responses/BadRequest'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '422':
+                    $ref: '#/components/responses/ValidationError'
+
+    /api/entities/types:
+        get:
+            tags:
+                - Entities
+            summary: List available entity types
+            description: Get a list of all available entity types (API modules) that can be integrated
+            operationId: listEntityTypes
+            responses:
+                '200':
+                    description: List of available entity types
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ListEntityTypesResponse'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+
+    /api/entities/types/{typeName}:
+        get:
+            tags:
+                - Entities
+            summary: Get entity type metadata
+            description: Retrieve detailed information about a specific entity type
+            operationId: getEntityType
+            parameters:
+                - $ref: '#/components/parameters/TypeName'
+            responses:
+                '200':
+                    description: Entity type metadata retrieved successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/EntityType'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+
+    /api/entities/types/{typeName}/requirements:
+        get:
+            tags:
+                - Entities
+            summary: Get authentication requirements for entity type
+            description: |
+                Get the authentication requirements (OAuth URLs, form schemas, etc.)
+                needed to authorize this entity type
+            operationId: getEntityTypeRequirements
+            parameters:
+                - $ref: '#/components/parameters/TypeName'
+                - name: step
+                  in: query
+                  schema:
+                      type: integer
+                      minimum: 1
+                      default: 1
+                  description: Step number for multi-step auth flows
+            responses:
+                '200':
+                    description: Authentication requirements retrieved successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/AuthorizationRequirements'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+
+    /api/entities/{entityId}:
+        get:
+            tags:
+                - Entities
+            summary: Get specific entity
+            description: Retrieve detailed information about a specific entity
+            operationId: getEntity
+            parameters:
+                - $ref: '#/components/parameters/EntityId'
+            responses:
+                '200':
+                    description: Entity retrieved successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/Entity'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+
+    /api/entities/{entityId}/test-auth:
+        get:
+            tags:
+                - Entities
+            summary: Test entity authentication
+            description: Verify that the entity's credentials are valid and working
+            operationId: testEntityAuth
+            parameters:
+                - $ref: '#/components/parameters/EntityId'
+            responses:
+                '200':
+                    description: Authentication test result
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/TestAuthResponse'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+
+    /api/entities/{entityId}/proxy:
+        post:
+            tags:
+                - Entities
+            summary: Proxy API request through entity
+            description: |
+                Forward an API request to the external system using the entity's credentials.
+                Automatically handles authentication headers and token refresh.
+            operationId: proxyEntityRequest
+            parameters:
+                - $ref: '#/components/parameters/EntityId'
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/ProxyRequest'
+            responses:
+                '200':
+                    description: Request proxied successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ProxyResponse'
+                '400':
+                    $ref: '#/components/responses/BadRequest'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+                '502':
+                    description: Upstream API error
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ProxyErrorResponse'
+
+    # Credential Endpoints
+    /api/credentials:
+        get:
+            tags:
+                - Credentials
+            summary: List user's credentials
+            description: Retrieve all credentials owned by the authenticated user (tokens masked)
+            operationId: listCredentials
+            responses:
+                '200':
+                    description: List of credentials retrieved successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ListCredentialsResponse'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+
+    /api/credentials/{credentialId}:
+        get:
+            tags:
+                - Credentials
+            summary: Get specific credential
+            description: Retrieve detailed information about a specific credential (tokens masked)
+            operationId: getCredential
+            parameters:
+                - $ref: '#/components/parameters/CredentialId'
+            responses:
+                '200':
+                    description: Credential retrieved successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/Credential'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+
+        delete:
+            tags:
+                - Credentials
+            summary: Delete credential
+            description: Delete a credential and all associated entities
+            operationId: deleteCredential
+            parameters:
+                - $ref: '#/components/parameters/CredentialId'
+            responses:
+                '200':
+                    description: Credential deleted successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/DeleteResponse'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+
+    /api/credentials/{credentialId}/reauthorize:
+        get:
+            tags:
+                - Credentials
+            summary: Get credential reauthorization requirements
+            description: Get authentication requirements to reauthorize an existing credential
+            operationId: getCredentialReauthorizationRequirements
+            parameters:
+                - $ref: '#/components/parameters/CredentialId'
+                - name: step
+                  in: query
+                  schema:
+                      type: integer
+                      minimum: 1
+                      default: 1
+            responses:
+                '200':
+                    description: Reauthorization requirements retrieved
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/AuthorizationRequirements'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+
+        post:
+            tags:
+                - Credentials
+            summary: Submit credential reauthorization
+            description: Reauthorize an existing credential with new authentication data
+            operationId: reauthorizeCredential
+            parameters:
+                - $ref: '#/components/parameters/CredentialId'
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/ReauthorizeRequest'
+            responses:
+                '200':
+                    description: Reauthorization completed or next step returned
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ReauthorizeResponse'
+                '400':
+                    $ref: '#/components/responses/BadRequest'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+                '422':
+                    $ref: '#/components/responses/ValidationError'
+
+    /api/credentials/{credentialId}/proxy:
+        post:
+            tags:
+                - Credentials
+            summary: Proxy API request through credential
+            description: |
+                Forward an API request to the external system using this credential.
+                Similar to entity proxy but doesn't require an entity to be created.
+            operationId: proxyCredentialRequest
+            parameters:
+                - $ref: '#/components/parameters/CredentialId'
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/ProxyRequest'
+            responses:
+                '200':
+                    description: Request proxied successfully
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ProxyResponse'
+                '400':
+                    $ref: '#/components/responses/BadRequest'
+                '401':
+                    $ref: '#/components/responses/Unauthorized'
+                '404':
+                    $ref: '#/components/responses/NotFound'
+                '502':
+                    description: Upstream API error
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ProxyErrorResponse'
+
+    # Health Endpoints
+    /health:
+        get:
+            tags:
+                - Health
+            summary: Basic health check
+            description: Simple health check endpoint that returns service status
+            operationId: healthCheck
+            security: []
+            responses:
+                '200':
+                    description: Service is healthy
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/HealthResponse'
+
+    /health/ready:
+        get:
+            tags:
+                - Health
+            summary: Readiness check
+            description: |
+                Detailed readiness check that validates database connectivity,
+                module loading, and encryption system status
+            operationId: readinessCheck
+            security: []
+            responses:
+                '200':
+                    description: Service is ready
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ReadinessResponse'
+                '503':
+                    description: Service not ready
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ReadinessResponse'
+
+components:
+    securitySchemes:
+        bearerAuth:
+            type: http
+            scheme: bearer
+            bearerFormat: JWT
+            description: JWT token obtained from authentication
+
+    parameters:
+        EntityId:
+            name: entityId
+            in: path
+            required: true
+            schema:
+                type: string
+            description: Unique entity identifier
+
+        CredentialId:
+            name: credentialId
+            in: path
+            required: true
+            schema:
+                type: string
+            description: Unique credential identifier
+
+        IntegrationId:
+            name: integrationId
+            in: path
+            required: true
+            schema:
+                type: string
+            description: Unique integration identifier
+
+        TypeName:
+            name: typeName
+            in: path
+            required: true
+            schema:
+                type: string
+            description: Entity type name (e.g., 'hubspot', 'salesforce')
+
+    schemas:
+        # v1-specific combined response
+        ListIntegrationsV1Response:
+            type: object
+            description: |
+                **v1 Combined Response Format**
+
+                This response combines entities and integrations in a single call for backwards compatibility.
+                In v2, these are split into separate endpoints for cleaner separation of concerns.
+            required:
+                - entities
+                - integrations
+            properties:
+                entities:
+                    type: object
+                    required:
+                        - options
+                        - authorized
+                    properties:
+                        options:
+                            type: array
+                            description: Available integration types that can be connected
+                            items:
+                                $ref: '#/components/schemas/IntegrationOption'
+                        authorized:
+                            type: array
+                            description: User's connected entities (accounts)
+                            items:
+                                $ref: '#/components/schemas/Entity'
+                integrations:
+                    type: array
+                    description: User's active integrations
+                    items:
+                        $ref: '#/components/schemas/Integration'
+
+        IntegrationOption:
+            type: object
+            description: An available integration type
+            required:
+                - type
+                - name
+            properties:
+                type:
+                    type: string
+                    description: Integration type identifier
+                name:
+                    type: string
+                    description: Display name
+                description:
+                    type: string
+                    description: Integration description
+                hasAuth:
+                    type: boolean
+                    description: Whether this integration requires authentication
+
+        ListIntegrationOptionsResponse:
+            type: object
+            required:
+                - integrations
+            properties:
+                integrations:
+                    type: array
+                    items:
+                        $ref: '#/components/schemas/IntegrationOption'
+
+        Entity:
+            type: object
+            description: A connected account/entity object representing an external integration
+            required:
+                - id
+                - type
+            properties:
+                id:
+                    type: string
+                    description: Unique entity identifier
+                type:
+                    type: string
+                    description: Module/entity type name (e.g., 'hubspot', 'salesforce')
+                name:
+                    type: string
+                    description: Display name for the entity
+                externalId:
+                    type: string
+                    description: ID from the external system (e.g., HubSpot portal ID)
+                credential_id:
+                    type: string
+                    description: ID of the linked credential
+                userId:
+                    type: string
+                    description: ID of the user who owns this entity
+                dateCreated:
+                    type: string
+                    format: date-time
+                    description: Entity creation timestamp
+                dateUpdated:
+                    type: string
+                    format: date-time
+                    description: Last update timestamp
+
+        ListEntitiesResponse:
+            type: object
+            required:
+                - entities
+            properties:
+                entities:
+                    type: array
+                    items:
+                        $ref: '#/components/schemas/Entity'
+
+        CreateEntityRequest:
+            type: object
+            required:
+                - entityType
+                - data
+            properties:
+                entityType:
+                    type: string
+                    description: Type of entity to create (module name)
+                data:
+                    type: object
+                    required:
+                        - credential_id
+                    properties:
+                        credential_id:
+                            type: string
+                            description: ID of the credential to link to this entity
+                    additionalProperties: true
+
+        CreateEntityResponse:
+            type: object
+            required:
+                - entity_id
+                - credential_id
+                - type
+            properties:
+                entity_id:
+                    type: string
+                credential_id:
+                    type: string
+                type:
+                    type: string
+
+        EntityType:
+            type: object
+            required:
+                - type
+                - name
+            properties:
+                type:
+                    type: string
+                    description: Module name (e.g., 'hubspot', 'salesforce')
+                name:
+                    type: string
+                    description: Display name
+                description:
+                    type: string
+                authType:
+                    type: string
+                    enum: [oauth2, form, api-key, basic]
+                isMultiStep:
+                    type: boolean
+                stepCount:
+                    type: integer
+                    minimum: 1
+                capabilities:
+                    type: array
+                    items:
+                        type: string
+
+        ListEntityTypesResponse:
+            type: object
+            required:
+                - types
+            properties:
+                types:
+                    type: array
+                    items:
+                        $ref: '#/components/schemas/EntityType'
+
+        TestAuthResponse:
+            type: object
+            properties:
+                valid:
+                    type: boolean
+                message:
+                    type: string
+
+        Credential:
+            type: object
+            description: A credential object (tokens are masked in responses)
+            required:
+                - id
+                - type
+            properties:
+                id:
+                    type: string
+                type:
+                    type: string
+                    description: Module type (e.g., 'hubspot', 'salesforce')
+                externalId:
+                    type: string
+                userId:
+                    type: string
+                dateCreated:
+                    type: string
+                    format: date-time
+                dateUpdated:
+                    type: string
+                    format: date-time
+
+        ListCredentialsResponse:
+            type: object
+            required:
+                - credentials
+            properties:
+                credentials:
+                    type: array
+                    items:
+                        $ref: '#/components/schemas/Credential'
+
+        Integration:
+            type: object
+            required:
+                - id
+                - userId
+            properties:
+                id:
+                    type: string
+                userId:
+                    type: string
+                config:
+                    type: object
+                    description: Integration configuration
+                status:
+                    type: string
+                    enum: [ENABLED, DISABLED, PAUSED, ERROR]
+                entities:
+                    type: array
+                    items:
+                        type: string
+                    description: Array of entity IDs
+                dateCreated:
+                    type: string
+                    format: date-time
+                dateUpdated:
+                    type: string
+                    format: date-time
+
+        CreateIntegrationRequest:
+            type: object
+            required:
+                - entities
+            properties:
+                entities:
+                    type: array
+                    items:
+                        type: string
+                    description: Array of entity IDs to integrate
+                config:
+                    type: object
+                    description: Integration configuration
+
+        UpdateIntegrationRequest:
+            type: object
+            properties:
+                config:
+                    type: object
+                enabled:
+                    type: boolean
+
+        AuthorizationRequirements:
+            type: object
+            required:
+                - type
+                - step
+                - totalSteps
+            properties:
+                type:
+                    type: string
+                    enum: [oauth2, form, api-key, basic]
+                step:
+                    type: integer
+                    minimum: 1
+                totalSteps:
+                    type: integer
+                    minimum: 1
+                isMultiStep:
+                    type: boolean
+                sessionId:
+                    type: string
+                data:
+                    oneOf:
+                        - $ref: '#/components/schemas/OAuth2Requirements'
+                        - $ref: '#/components/schemas/FormRequirements'
+                        - $ref: '#/components/schemas/ApiKeyRequirements'
+
+        OAuth2Requirements:
+            type: object
+            required:
+                - url
+            properties:
+                url:
+                    type: string
+                    format: uri
+                scopes:
+                    type: array
+                    items:
+                        type: string
+
+        FormRequirements:
+            type: object
+            required:
+                - jsonSchema
+            properties:
+                jsonSchema:
+                    type: object
+                uiSchema:
+                    type: object
+
+        ApiKeyRequirements:
+            type: object
+            required:
+                - fields
+            properties:
+                fields:
+                    type: array
+                    items:
+                        type: object
+                        properties:
+                            name:
+                                type: string
+                            type:
+                                type: string
+                                enum: [api_key, secret, token]
+                            label:
+                                type: string
+                            required:
+                                type: boolean
+
+        AuthorizationRequest:
+            type: object
+            required:
+                - entityType
+            properties:
+                entityType:
+                    type: string
+                data:
+                    type: object
+                    additionalProperties: true
+                step:
+                    type: integer
+                    minimum: 1
+                    default: 1
+                sessionId:
+                    type: string
+
+        AuthorizationResponse:
+            oneOf:
+                - $ref: '#/components/schemas/AuthorizationSuccess'
+                - $ref: '#/components/schemas/AuthorizationNextStep'
+
+        AuthorizationSuccess:
+            type: object
+            required:
+                - entity_id
+                - credential_id
+                - type
+            properties:
+                entity_id:
+                    type: string
+                credential_id:
+                    type: string
+                type:
+                    type: string
+
+        AuthorizationNextStep:
+            type: object
+            required:
+                - nextStep
+                - sessionId
+                - requirements
+            properties:
+                nextStep:
+                    type: integer
+                    minimum: 2
+                sessionId:
+                    type: string
+                requirements:
+                    $ref: '#/components/schemas/AuthorizationRequirements'
+
+        ReauthorizeRequest:
+            type: object
+            required:
+                - data
+            properties:
+                data:
+                    type: object
+                    additionalProperties: true
+                step:
+                    type: integer
+                    minimum: 1
+                    default: 1
+                sessionId:
+                    type: string
+
+        ReauthorizeResponse:
+            oneOf:
+                - $ref: '#/components/schemas/ReauthorizeSuccess'
+                - $ref: '#/components/schemas/ReauthorizeNextStep'
+
+        ReauthorizeSuccess:
+            type: object
+            required:
+                - success
+                - credential_id
+            properties:
+                success:
+                    type: boolean
+                credential_id:
+                    type: string
+                entity_id:
+                    type: string
+
+        ReauthorizeNextStep:
+            type: object
+            required:
+                - step
+                - totalSteps
+                - sessionId
+                - requirements
+            properties:
+                step:
+                    type: integer
+                totalSteps:
+                    type: integer
+                sessionId:
+                    type: string
+                requirements:
+                    type: object
+
+        ProxyRequest:
+            type: object
+            required:
+                - method
+                - path
+            properties:
+                method:
+                    type: string
+                    enum: [GET, POST, PUT, PATCH, DELETE]
+                path:
+                    type: string
+                    pattern: ^/
+                query:
+                    type: object
+                    additionalProperties: true
+                headers:
+                    type: object
+                    additionalProperties:
+                        type: string
+                body:
+                    oneOf:
+                        - type: object
+                        - type: array
+                        - type: string
+                        - type: 'null'
+
+        ProxyResponse:
+            type: object
+            required:
+                - success
+                - status
+                - data
+            properties:
+                success:
+                    type: boolean
+                status:
+                    type: integer
+                headers:
+                    type: object
+                    additionalProperties:
+                        type: string
+                data:
+                    description: Response body from upstream API
+
+        ProxyErrorResponse:
+            type: object
+            required:
+                - success
+                - status
+                - error
+            properties:
+                success:
+                    type: boolean
+                    enum: [false]
+                status:
+                    type: integer
+                error:
+                    type: object
+                    required:
+                        - code
+                        - message
+                    properties:
+                        code:
+                            type: string
+                            enum:
+                                - INVALID_AUTH
+                                - EXPIRED_TOKEN
+                                - UPSTREAM_ERROR
+                                - TIMEOUT
+                                - NETWORK_ERROR
+                                - RATE_LIMITED
+                        message:
+                            type: string
+                        details:
+                            type: object
+                        upstreamStatus:
+                            type: integer
+
+        DeleteResponse:
+            type: object
+            required:
+                - success
+            properties:
+                success:
+                    type: boolean
+                message:
+                    type: string
+
+        HealthResponse:
+            type: object
+            properties:
+                status:
+                    type: string
+                    example: ok
+                timestamp:
+                    type: string
+                    format: date-time
+
+        ReadinessResponse:
+            type: object
+            properties:
+                ready:
+                    type: boolean
+                timestamp:
+                    type: string
+                    format: date-time
+                checks:
+                    type: object
+                    properties:
+                        database:
+                            type: boolean
+                        modules:
+                            type: boolean
+                        encryption:
+                            type: object
+                            properties:
+                                status:
+                                    type: string
+                                testResult:
+                                    type: string
+
+        Error:
+            type: object
+            required:
+                - error
+            properties:
+                error:
+                    type: object
+                    required:
+                        - code
+                        - message
+                    properties:
+                        code:
+                            type: string
+                        message:
+                            type: string
+                        details:
+                            type: object
+
+    responses:
+        BadRequest:
+            description: Bad request - invalid input
+            content:
+                application/json:
+                    schema:
+                        $ref: '#/components/schemas/Error'
+                    example:
+                        error:
+                            code: BAD_REQUEST
+                            message: Invalid request parameters
+
+        Unauthorized:
+            description: Unauthorized - missing or invalid authentication
+            content:
+                application/json:
+                    schema:
+                        $ref: '#/components/schemas/Error'
+                    example:
+                        error:
+                            code: UNAUTHORIZED
+                            message: Authentication required
+
+        NotFound:
+            description: Resource not found
+            content:
+                application/json:
+                    schema:
+                        $ref: '#/components/schemas/Error'
+                    example:
+                        error:
+                            code: NOT_FOUND
+                            message: Resource not found
+
+        ValidationError:
+            description: Validation error - invalid data
+            content:
+                application/json:
+                    schema:
+                        $ref: '#/components/schemas/Error'
+                    example:
+                        error:
+                            code: VALIDATION_ERROR
+                            message: Data validation failed