Portway is a lightweight API gateway for Windows and Linux containers that simplifies secure service routing and infrastructure management.
It unifies databases, internal services, and webhooks into a single interface using simple, file-based configuration. Built-in caching, audit logging, and automated documentation keep your data flow reliable and easy to control.
Out of the box, Portway handles proxy pass-through, SQL endpoints, and webhooks, with native support for MCP and OData. It also includes Azure Key Vault authentication, rate limiting, management (web) console and full observability through Prometheus or any OTLP collector.
Before deploying Portway, make sure your environment meets the following requirements. These ensure full functionality across all features, especially SQL and authentication.
- .NET Hosting Bundle
- Preview >=
v0.7.0: .NET 11 (currently a preview) - Production: .NET 10 LTS build remains available
- Preview >=
- If you're running on Windows: Internet Information Services (IIS)
- A supported SQL database (if you're using SQL endpoints): SQL Server, PostgreSQL, MySQL/MariaDB, or SQLite
Ready to go? Then lets continue:
Follow these steps to get Portway up and running in your environment. Setup is fast and modular, making it easy to configure just what you need.
Grab the latest release and extract it to your deployment folder. This build already includes a set of example environment and endpoint configurations.
Note, before configuring the application in Internet Information Services, make sure to configure your environment-specific secret:
$bytes = New-Object byte[] 48; [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes); [Environment]::SetEnvironmentVariable("PORTWAY_ENCRYPTION_KEY", [Convert]::ToBase64String($bytes), "Machine")On containerized environments, this can be done with the identically named PORTWAY_ENCRYPTION_KEY variable.
You can quickly deploy Portway using Docker Compose and the official image:
services:
portway:
image: ghcr.io/melosso/portway:latest
ports:
- "8080:8080"
volumes:
- portway_app:/app
- ./environments:/app/environments
- ./endpoints:/app/endpoints
- ./tokens:/app/tokens
- ./log:/app/log
- ./data:/app/data
environment:
# Set your encryption secret here (e.g. use openssl rand -hex 32)
- PORTWAY_ENCRYPTION_KEY=YourEncryptionKeyHere
# Configure CORS, prefix and access token
- AllowedHosts=*
- PathBase=
- WebUi__AdminApiKey=INSECURE-CHANGE-ME-admin-api-key
volumes:
portway_app:Then run:
docker compose pull && docker compose up -dThis will start Portway on port 8080 and mount your configuration folders. Adjust paths and ports as needed for your environment. Before you can start using the API, you'll have to configure your environment settings and endpoint configurations.
Define your server and environment settings to isolate the various environments you may require (e.g. prod and dev). These configurations are used across the endpoints that you'll configure later on. First configure the allowed environments, after which the individual environment has to be defined:
environments/settings.json
{
"Environment": {
"ServerName": "localhost",
"AllowedEnvironments": ["prod", "dev"]
}
}environments/prod/settings.json
{
"ServerName": "localhost",
"ConnectionString": "Server=localhost;Database=prod;Trusted_Connection=True;Connection Timeout=5;TrustServerCertificate=true;"
}Endpoints are configured as JSON files. Each type has its own directory and format, making them easy to manage and extend. These are plain examples, for more advanced configuration you may have to read our extensive documentation on our documentation page. There are various types that Portway supports:
- SQL (SQL Server, PostgreSQL, MySQL, SQLite): Direct CRUD access with schema-level control and documentation
- Proxy: Forward to internal services; supports complex orchestration
- Composite: Chain multiple endpoint calls into one transaction
- File System: Read/write from local storage or cache (In memory and/or Redis)
- Webhook: Receive external calls and persist data to SQL
- Static: read static files or set up a mock endpoint
These are handled seperately below. Once configured, the request side of each type is shown under Examples.
SQL Endpoints
These point straight at your database tables. You choose which columns get exposed and what their public names should be. It keeps the surface area clean and lets you hide internal schemas or naming quirks.{
"DatabaseObjectName": "Items",
"DatabaseSchema": "dbo",
"PrimaryKey": "ItemCode",
"AllowedColumns": [
"ItemCode;ProductNumber",
"LongDescription;Description",
"Assortment;AssortmentCode",
"sysguid;InternalID"
],
"AllowedEnvironments": ["prod", "dev"]
}Proxy Endpoints
These just pass the call through to another service. It’s basically a small reverse proxy where you decide which HTTP verbs you want to support.{
"Url": "http://localhost:8020/services/Exact.Entity.REST.EG/Account",
"Methods": ["GET", "POST", "PUT", "DELETE", "MERGE"],
"AllowedEnvironments": ["prod", "dev"]
}Composite Endpoints
These help when a single logical action actually means “call a bunch of other endpoints in a specific order.” Think of creating an order with multiple lines and a header. You wire the steps together and the engine handles the sequencing.{
"Type": "Composite",
"Url": "http://localhost:8020/services/Exact.Entity.REST.EG",
"Methods": ["POST"],
"CompositeConfig": {
"Name": "SalesOrder",
"Description": "Creates a complete sales order with multiple lines and header",
"Steps": [
{
"Name": "CreateOrderLines",
"Endpoint": "SalesOrderLine",
"Method": "POST",
"IsArray": true,
"ArrayProperty": "Lines",
"TemplateTransformations": {
"TransactionKey": "$guid"
}
},
{
"Name": "CreateOrderHeader",
"Endpoint": "SalesOrderHeader",
"Method": "POST",
"SourceProperty": "Header",
"TemplateTransformations": {
"TransactionKey": "$prev.CreateOrderLines.0.d.TransactionKey"
}
}
]
}
}Static Endpoints
Sometimes you just want to serve a file. JSON, XML, CSV, whatever. These endpoints expose static content and can still use OData filtering if you turn it on.{
"ContentType": "application/xml",
"ContentFile": "summary.xml",
"EnableFiltering": true,
"AllowedEnvironments": ["prod", "dev"]
}Files Endpoints
This is for storing or retrieving actual files rather than rows or JSON. Handy for documents, images, exports.{
"StorageType": "Local",
"BaseDirectory": "documents",
"AllowedExtensions": [".pdf", ".docx", ".xlsx", ".txt"],
"AllowedEnvironments": ["prod", "dev"]
}Webhook Endpoints
When an external service needs to push data into your system, this is the entry point. The payload goes straight into your table of choice.{
"DatabaseObjectName": "WebhookData",
"DatabaseSchema": "dbo",
"AllowedColumns": ["webhook1", "webhook2"]
}When you're ready to host in IIS or Docker, follow the deployment guide. It covers application pool identity (needed for NTLM proxy scenarios), security settings, and production hardening.
Portway uses a lightweight token-based system for authentication. Include the token in request headers, with the Bearer prefix included:
Authorization: Bearer YOUR_TOKEN_HEREThe first-run token file, scope control, Azure Key Vault, secret encryption at rest, and application identity for NTLM scenarios are covered in the security guide.
Here are some common requests you'll make using Portway's endpoints.
SQL
Query specific data with full OData support:
GET /api/prod/Products?$filter=Assortment eq 'Books'&$select=ItemCode,DescriptionProxy
Forward calls to internal REST services:
GET /api/prod/Accounts
POST /api/prod/AccountsComposite
Chain together multiple operations into one:
POST /api/prod/composite/SalesOrder
Content-Type: application/json
{
"Header": {
"OrderDebtor": "60093",
"YourReference": "Connect async"
},
"Lines": [
{ "Itemcode": "ITEM-001", "Quantity": 2, "Price": 0 },
{ "Itemcode": "ITEM-002", "Quantity": 4, "Price": 0 }
]
}Static
Serve static content with optional OData filtering:
GET /api/prod/ProductionMachine?$top=1&$filter=status eq 'running'
Accept: application/xmlFiles
Upload, list, and download files:
POST /api/prod/files/Documents
Content-Type: multipart/form-data
file=@report.pdf
GET /api/prod/files/Documents/list
GET /api/prod/files/Documents/abc123fileIdWebhooks
Receive data from external services:
POST /api/prod/Integrations/Inbound/webhook1
Content-Type: application/json
{
"eventType": "order.created",
"data": {
"orderId": "12345",
"customer": "ACME Corp"
}
}You'll find comprehensive configuration examples in our documentation page.
We allow you to expose the API with a configurable documentation endpoint. This can be disabled if necessary.
The application uses Scalar to render your OpenAPI specification as interactive API documentation. Access it at /docs to explore endpoints, test requests, and view response schemas, which are all generated automatically from your endpoint configurations.
The application also can act as a MCP server over HTTP. Your endpoints can appear in the MCP tool registry and becomes callable by any MCP-compatible client, e.g. Mistral, VS Code Copilot, custom agents, or the built-in Chat UI. Beware that this is opt-in, meaning all endpoints are not exposed as tool by default. Portway's own authentication and environment scoping apply to every tool call. Please read more on MCP integration at MCP documentation.
Our documentation page will walk you through setting up Portway. This covers both basic usage, and advanced configuration. Feel free to submit a pull request if you'd like to see changes to the documentation.
Contributions are welcome, please submit a PR if you'd like to help improve the project.
Licensed under the EUPL-1.2. For more information, please see the license file.