AI API Mapper
Technical walkthrough →
Technical walkthrough →
/ docs · functional specification

The full platform
functional reference.

Every functional area of AI API Mapper documented at implementation depth so architects, security reviewers, and platform engineers can evaluate the product with real technical context.

Platform · Overview
On this page

AI API Mapper Platform Overview

Purpose

The AI API Mapper Platform is a tenant-aware application that turns existing enterprise HTTP APIs into governed tools that AI agents and copilots can safely discover and invoke.

From a functional standpoint, the platform sits between:

  • business APIs that were originally designed for web, mobile, or system-to-system integrations
  • AI clients that need stable tool definitions, structured inputs, secure credentials, and auditable execution

Instead of exposing raw downstream APIs directly to AI callers, the platform adds onboarding, mapping, publication, runtime execution, identity, governance, and operational control.

Which Problem It Solves

The platform addresses a common enterprise gap:

  • downstream APIs often expose technical operations, inconsistent payloads, and authentication schemes that are difficult for AI clients to use directly
  • AI tools need clear names, typed inputs, predictable outputs, and a controlled execution boundary
  • organizations need to know who invoked what, under which tenant, with which credentials, and whether the call complied with policy

The platform resolves this by letting administrators:

  • import API definitions from OpenAPI and SOAP/WSDL contracts
  • inspect protocol-aware operation metadata, request/response schemas, SOAP headers, and fault shapes after import
  • define and refine functional mappings for selected operations
  • publish those mappings as AI-facing tools
  • bind tools to downstream target systems and authentication profiles
  • enforce access policies and runtime governance
  • observe runtime activity, enrichment activity, and platform security events

Main Functional Flow

At a high level, the application works like this:

  1. An administrator uses the Portal to onboard an API from an OpenAPI or SOAP/WSDL document.
  2. The platform creates a mapping proposal that turns selected API operations into business-friendly tool definitions.
  3. Administrators review, edit, approve, version, and publish the mapping.
  4. The published mapping is added to a toolset — alongside any other mappings that belong in the same tool catalog — and the toolset is assigned to one or more client applications.
  5. Administrators configure downstream connectivity, authentication strategies, secret sources, and runtime access policies.
  6. An AI client calls the Runtime to list available tools or invoke a specific tool for a tenant and client application.
  7. The Runtime authorizes the caller, resolves credentials, transforms the request, calls the downstream API, transforms the response, and writes audit data.
  8. Background jobs process asynchronous work such as semantic enrichment and data retention.

Platform Architecture

The platform is implemented as a modular monolith with separate executable hosts for administration, runtime execution, background processing, and gateway routing.

The main building blocks are:

  • business modules for onboarding, mapping, runtime, governance, identity, downstream security, tenants, jobs, secrets, and notifications
  • a shared persistence model backed by a platform database
  • a dedicated runtime surface for AI callers
  • a dedicated portal surface for human administrators
  • background workers for asynchronous processing and scheduled maintenance
  • a reverse proxy entry point

Main Components

The platform is organized around five main platform components:

  • Portal Handles administration, configuration, governance monitoring, identity management, and the operator web experience.
  • Runtime Exposes published tools to AI clients and executes governed downstream calls.
  • Jobs Worker Runs asynchronous and scheduled workloads such as semantic enrichment and data retention.
  • Gateway Provides the reverse-proxy entry point in front of the externally exposed portal and runtime services.
  • SDK Client libraries for .NET, TypeScript, Python, and Java that integrate with the Runtime without writing any MCP or HTTP plumbing.

Supported Databases

The Portal, Runtime, and Jobs Worker use the same shared platform database and platform data model.

Supported Integrations

The platform currently includes first-class functional support for:

  • Microsoft Entra ID Used for external portal sign-in and related claim mapping, tenant-aware provider configuration, and user linking/provisioning flows.
  • Keycloak Used for external portal sign-in using the OIDC Authorization Code + PKCE flow, with the same claim mapping and tenant-aware provider configuration available for Microsoft Entra ID.
  • Azure Key Vault Used as a supported managed secret store for runtime and administrative secret resolution.

The platform also supports related integration patterns such as:

  • OpenAPI and SOAP/WSDL import for onboarding downstream APIs
  • OIDC and JWT-based trust for runtime callers
  • HTTP and SOAP downstream invocation
  • SignalR notifications in the portal
  • Message-driven background processing with configurable transport options

Governance Supported

The platform provides governance in several layers.

Runtime access governance includes:

  • default-deny tool authorization when no active policy matches
  • per-tool access policies based on issuer, client ID, roles, scopes, groups, and custom claim requirements
  • tenant-aware policy evaluation

Execution governance includes:

  • audit records for runtime activity
  • durable external audit delivery through compliance or operational targets
  • end-to-end call trace inspection by correlation ID with per-step timing
  • configurable audit event filtering by category, action, and outcome
  • opt-in request and response payload capture for MCP and downstream traffic with automatic sanitization and truncation
  • enrichment run monitoring for AI-assisted mapping generation, including per-chunk LLM traceability and token usage

External audit delivery supports deployment-managed compliance sinks and UI-managed operational sinks. Compliance targets can fan out to HTTPS REST endpoints, TLS syslog receivers, SQL Server tables, or PostgreSQL tables, while the platform persists the canonical audit event and append-only delivery-attempt history before any external send is attempted.

Security governance includes:

  • outbound host allowlists for downstream calls
  • authentication hardening and rate limiting
  • trusted identity provider administration
  • secret-store administration and managed secret usage
  • retention policies for governance and session data

Security Assurance

Governance is what the platform enforces at runtime. Assurance is how the platform itself is verified before it ships, and the two are separate questions a security review will ask separately.

Every release is scanned by tools/security-scan.sh across sixteen layers — eighteen rows in the report, since the SBOM and container layers each run two tools — every one answering a question the others cannot:

  • Static analysis of the source, against OWASP Top 10, CWE Top 25 and language-specific rule packs.
  • Software composition, cross-checked against four independent vulnerability databases — Trivy, OSV, NuGet's own advisory feed and npm's — because none of them is a superset of the others.
  • Secrets, in the working tree and across the whole git history.
  • A software bill of materials, published in SPDX 2.3 and CycloneDX 1.6, and then scanned in its own right.
  • The published container images, including the .NET shared framework that no package-manifest scanner can see, and the Dockerfiles against the CIS Docker benchmark.
  • The infrastructure definitions, for privileges granted beyond what a service needs.
  • A live attack against the running Gateway, Portal.Api and Runtime.Host — active scanning, known-CVE probing and TLS posture. The AI-facing runtime's discovery surface, including the OAuth metadata that tells your AI clients which authorization server to trust, is scanned with a seeded tenant's credential.
  • Our own published MCP tool descriptions, scanned for poisoning with Cisco's open-source MCP Scanner. Tool descriptions here are synthesised by an LLM from customer-supplied API specifications, so this asks whether a hostile specification could turn the platform into a delivery vehicle for a prompt-injection payload aimed at every connected AI client.

The run produces a printable posture report naming the exact image tag, registry and commit it examined, alongside every tool's untouched output. Two properties make it evidence rather than a number:

  • A scanner that could not run fails the release gate, exactly as a finding does. A layer reporting "clean" because its tool was absent is worse than no layer at all, and the report says plainly when the live attack did not happen.
  • A finding judged not to be a defect is recorded in the source, with the reasoning beside the code, rather than filtered out of a report. The judgement travels with what it describes.
  • A layer says what it did not judge. The TLS layer run against a self-hosted stack is inspecting a certificate the scan itself generated, so certificate and PKI findings are counted and named in that row but not gated — grading them would be the report marking its own scaffolding. Run with --target against a real deployment they gate like everything else, and that is the mode whose TLS verdict means something.

The live-attack layer raises the scan stack's own rate limits for the duration of a run. This is deliberate and changes nothing about a deployment: an active scanner sends far more traffic than the limits allow, and a throttled target makes it compare a refusal against an answer — which it reports as an injection, in a different place each run. Rate limiting is verified by tests that demand the 429; the attack layer exists to see the application behind the limiter, and cannot do that through a closed bucket.

Base images are pinned to an exact patch release rather than to a moving tag, and the pins are reviewed against upstream at every release — a floating base makes the image a report describes and the image you run two different artefacts that happen to share a name.

NextOverviewPortal