openapi: 3.1.0
info:
  title: Mappls Integration Fabric Control API
  version: 2.0.0
  description: >-
    Tenant-aware control API for API products, applications, subscriptions,
    gateways, integrations, durable workflows, messaging, policy, releases,
    observability, security, service operations and audit. NABARD Enterprise is
    represented as a configured customer organization and workspace set.
  contact:
    name: Mappls Integration Fabric Product Engineering
servers:
  - url: https://nabardapi.mapplsgov.com
    description: Published customer solution
  - url: http://localhost:3000
    description: Local product environment
tags:
  - { name: Platform, description: Product and workspace context }
  - { name: Identity, description: Evaluation sessions and current identity }
  - { name: API Products, description: Contract and lifecycle management }
  - { name: Applications, description: Workload identity and credential lifecycle }
  - { name: Access, description: Plans and maker-checker subscription decisions }
  - { name: Integration, description: Reusable connectors and mediation assets }
  - { name: Workflows, description: Durable stateful orchestration }
  - { name: Messaging, description: Queues, topics, DLQ and replay }
  - { name: Policy, description: Versioned runtime policy }
  - { name: Releases, description: Environment promotion and rollback }
  - { name: Operations, description: Runtime health, observability and incidents }
  - { name: Administration, description: Organizations, workspaces and users }
  - { name: Assurance, description: Security, compliance and audit evidence }
security:
  - cookieSession: []
  - bearerAuth: []
paths:
  /api/health:
    get:
      tags: [Platform]
      security: []
      summary: Read service health, product release and availability objective
      responses:
        '200': { description: Healthy, content: { application/json: { schema: { $ref: '#/components/schemas/Health' } } } }
  /api/auth/demo:
    post:
      tags: [Identity]
      security: []
      summary: Create a permission-scoped evaluation session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [role]
              properties:
                role: { type: string, enum: [consumer, developer, product_manager, tenant_admin, platform_admin, auditor, support, super_admin] }
      responses:
        '200': { description: Session created }
        '400': { $ref: '#/components/responses/BadRequest' }
  /api/auth/logout:
    post:
      tags: [Identity]
      summary: End the current session
      parameters: [{ $ref: '#/components/parameters/Csrf' }]
      responses: { '200': { description: Session ended } }
  /api/me:
    get:
      tags: [Identity]
      summary: Read current identity, workspace and permissions
      responses: { '200': { description: Current identity }, '401': { $ref: '#/components/responses/Unauthorized' } }
  /api/platform/summary:
    get:
      tags: [Platform]
      summary: Read product, organization, workspace and capability context
      responses: { '200': { description: Platform context } }
  /api/dashboard:
    get:
      tags: [Platform, Operations]
      summary: Read role-scoped command-centre metrics and attention items
      responses: { '200': { description: Dashboard } }
  /api/solution-blueprint:
    get:
      tags: [Platform]
      summary: Read accountable product plane boundaries
      responses: { '200': { description: Product architecture } }
  /api/catalog/apis:
    get:
      tags: [API Products]
      summary: List API products visible to the caller
      responses: { '200': { description: API product list } }
    post:
      tags: [API Products]
      summary: Create a contract-first API product draft
      parameters: [{ $ref: '#/components/parameters/Csrf' }, { $ref: '#/components/parameters/Idempotency' }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ApiProductInput' }
      responses: { '201': { description: Draft created }, '403': { $ref: '#/components/responses/Forbidden' } }
  /api/catalog/apis/{id}/action:
    post:
      tags: [API Products]
      summary: Publish, deprecate, retire, stop or restore an API product
      parameters: [{ $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/Csrf' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [action, reason]
              properties:
                action: { type: string, enum: [publish, deprecate, retire, kill, restore] }
                reason: { type: string }
      responses: { '200': { description: Lifecycle action recorded }, '403': { $ref: '#/components/responses/Forbidden' } }
  /api/applications:
    get:
      tags: [Applications]
      summary: List workload applications and credential posture
      responses: { '200': { description: Application list } }
    post:
      tags: [Applications]
      summary: Register a workload application
      parameters: [{ $ref: '#/components/parameters/Csrf' }, { $ref: '#/components/parameters/Idempotency' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, environment, auth]
              properties:
                name: { type: string }
                environment: { type: string }
                auth: { type: string }
      responses: { '201': { description: Application registered } }
  /api/applications/{id}/rotate:
    post:
      tags: [Applications]
      summary: Rotate application credentials without exposing secret material
      parameters: [{ $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/Csrf' }]
      responses: { '200': { description: Credential fingerprint and new expiry } }
  /api/access-requests:
    get:
      tags: [Access]
      summary: List visible subscription requests
      responses: { '200': { description: Request list } }
    post:
      tags: [Access]
      summary: Request an API plan for an application
      parameters: [{ $ref: '#/components/parameters/Csrf' }, { $ref: '#/components/parameters/Idempotency' }]
      responses: { '201': { description: Request submitted } }
  /api/access-requests/{id}/decision:
    post:
      tags: [Access]
      summary: Record a maker-checker entitlement decision
      parameters: [{ $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/Csrf' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [decision, reason]
              properties:
                decision: { type: string, enum: [approved, rejected] }
                reason: { type: string }
      responses: { '200': { description: Decision recorded }, '403': { $ref: '#/components/responses/Forbidden' } }
  /api/integrations:
    get:
      tags: [Integration]
      summary: List integration assets and supported protocols
      responses: { '200': { description: Integration catalogue } }
    post:
      tags: [Integration]
      summary: Create a reusable integration asset
      parameters: [{ $ref: '#/components/parameters/Csrf' }]
      responses: { '201': { description: Integration draft created } }
  /api/orchestrations:
    get:
      tags: [Workflows]
      summary: List durable workflow definitions
      responses: { '200': { description: Workflow list } }
    post:
      tags: [Workflows]
      summary: Create a durable workflow definition
      parameters: [{ $ref: '#/components/parameters/Csrf' }]
      responses: { '201': { description: Workflow created } }
  /api/orchestrations/{id}/run:
    post:
      tags: [Workflows]
      summary: Start or safely repeat a durable workflow run
      parameters: [{ $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/Csrf' }, { $ref: '#/components/parameters/Idempotency' }]
      responses: { '202': { description: Run persisted and advanced to completion or wait state } }
  /api/runs:
    get:
      tags: [Workflows, Operations]
      summary: List correlated workflow run history
      responses: { '200': { description: Run list } }
  /api/runs/{id}/resume:
    post:
      tags: [Workflows, Operations]
      summary: Approve and resume a waiting workflow from its checkpoint
      parameters: [{ $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/Csrf' }]
      responses: { '200': { description: Run resumed }, '409': { description: Run is not waiting } }
  /api/messaging:
    get:
      tags: [Messaging]
      summary: Read queues, topics, throughput, retention and DLQ posture
      responses: { '200': { description: Event mesh posture } }
  /api/messaging/{id}/replay:
    post:
      tags: [Messaging, Operations]
      summary: Replay a bounded dead-letter message set with reason
      parameters: [{ $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/Csrf' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                limit: { type: integer, minimum: 1 }
                reason: { type: string }
      responses: { '200': { description: Replay executed }, '403': { $ref: '#/components/responses/Forbidden' } }
  /api/policies:
    get:
      tags: [Policy]
      summary: List versioned policy bundles and available controls
      responses: { '200': { description: Policy library } }
  /api/policies/{id}/action:
    post:
      tags: [Policy]
      summary: Submit, approve or roll back a policy revision
      parameters: [{ $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/Csrf' }]
      responses: { '200': { description: Policy lifecycle updated } }
  /api/releases:
    get:
      tags: [Releases]
      summary: List environment promotions and quality evidence
      responses: { '200': { description: Release list } }
  /api/releases/{id}/action:
    post:
      tags: [Releases]
      summary: Approve, reject or roll back an environment promotion
      parameters: [{ $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/Csrf' }]
      responses: { '200': { description: Release decision recorded } }
  /api/gateways:
    get:
      tags: [Operations]
      summary: Read gateway groups, nodes, capacity and runtime health
      responses: { '200': { description: Gateway topology } }
  /api/gateways/{id}/action:
    post:
      tags: [Operations]
      summary: Drain, restore or rolling-restart a gateway group
      parameters: [{ $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/Csrf' }]
      responses: { '200': { description: Runtime action accepted } }
  /api/observability:
    get:
      tags: [Operations]
      summary: Read SLOs, traffic, latency, errors and alerts
      responses: { '200': { description: Operational analytics } }
  /api/incidents:
    get:
      tags: [Operations]
      summary: List incidents and severity restoration objectives
      responses: { '200': { description: Incident list } }
    post:
      tags: [Operations]
      summary: Open an incident and start its SLA clock
      parameters: [{ $ref: '#/components/parameters/Csrf' }]
      responses: { '201': { description: Incident opened } }
  /api/tenants:
    get:
      tags: [Administration]
      summary: List authorized organizations and workspaces
      responses: { '200': { description: Organization and workspace list } }
    post:
      tags: [Administration]
      summary: Start isolated workspace provisioning
      parameters: [{ $ref: '#/components/parameters/Csrf' }]
      responses: { '201': { description: Provisioning started } }
  /api/users:
    get:
      tags: [Administration]
      summary: List workspace users, roles, MFA and access-review posture
      responses: { '200': { description: User list } }
    post:
      tags: [Administration]
      summary: Invite a workspace user with a named role
      parameters: [{ $ref: '#/components/parameters/Csrf' }]
      responses: { '201': { description: Invitation created } }
  /api/admin/impersonate:
    post:
      tags: [Administration, Assurance]
      summary: Start time-bound, reasoned and audited support access
      parameters: [{ $ref: '#/components/parameters/Csrf' }]
      responses: { '200': { description: Support access started } }
  /api/admin/impersonate/stop:
    post:
      tags: [Administration, Assurance]
      summary: End active support access and restore home workspace
      parameters: [{ $ref: '#/components/parameters/Csrf' }]
      responses: { '200': { description: Support access stopped } }
  /api/security:
    get:
      tags: [Assurance]
      summary: Read security control and certificate posture
      responses: { '200': { description: Security posture } }
  /api/compliance-evidence:
    get:
      tags: [Assurance]
      summary: Read customer-specific requirement-to-evidence mapping
      responses: { '200': { description: Customer assurance register }, '403': { $ref: '#/components/responses/Forbidden' } }
  /api/audit:
    get:
      tags: [Assurance]
      summary: Read append-only privileged and lifecycle evidence
      responses: { '200': { description: Audit events }, '403': { $ref: '#/components/responses/Forbidden' } }
components:
  securitySchemes:
    cookieSession: { type: apiKey, in: cookie, name: mif_session }
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
    mutualTls: { type: mutualTLS }
  parameters:
    Id: { name: id, in: path, required: true, schema: { type: string } }
    Csrf: { name: X-CSRF-Token, in: header, required: false, description: Required for browser-session mutations, schema: { type: string } }
    Idempotency: { name: Idempotency-Key, in: header, required: false, description: Required for safely repeatable production mutations, schema: { type: string, maxLength: 128 } }
  responses:
    BadRequest: { description: Request validation failed }
    Unauthorized: { description: Authentication required }
    Forbidden: { description: Caller lacks the required role, permission or tenant context }
  schemas:
    Health:
      type: object
      required: [status, service, edition, availabilityTarget, release, time]
      properties:
        status: { type: string, const: ok }
        service: { type: string, const: Mappls Integration Fabric }
        edition: { type: string }
        customerWorkspace: { type: string }
        availabilityTarget: { type: string }
        release: { type: string }
        time: { type: string, format: date-time }
    ApiProductInput:
      type: object
      required: [name]
      properties:
        name: { type: string, minLength: 3 }
        version: { type: string, default: 0.1.0 }
        protocol: { type: string, enum: [REST, AsyncAPI, SOAP, gRPC] }
        visibility: { type: string, enum: [internal, partner, public] }
        auth: { type: string }
        owner: { type: string }
        tags: { type: array, items: { type: string } }