Environments

The environment segment in /api/{environment}/{endpoint} selects a folder under environments/ with the connection string, server name, headers and authentication for that target.

Directory structure ​

environments/
├── settings.json              # Global: allowed environment names and server name
├── network-access-policy.json # SSRF protection for Proxy endpoints
├── prod/
│   └── settings.json          # Production connection string, headers, auth
├── test/
│   └── settings.json
└── dev/
    └── settings.json

Global settings ​

The global file environments/settings.json lists the routable environments:

{
  "Environment": {
    "ServerName": "SERVERNAME",
    "AllowedEnvironments": ["prod", "dev", "test"]
  }
}

ServerName is the default server name in forwarded headers. Property reference: Environment settings.

Environment settings ​

Per-environment settings.json:

{
  "ServerName": "PROD-SQL-CLUSTER",
  "ConnectionString": "Server=PROD-SQL-CLUSTER;Database=ProductionDB;Integrated Security=True;TrustServerCertificate=true;",
  "Headers": {
    "DatabaseName": "ProductionDB",
    "Origin": "Portway"
  }
}

SQL provider detection ​

The SQL provider is detected from the connection string. Detection rules and provider differences: SQL Providers.

{ "ConnectionString": "Data Source=environments/demo/demo.db;" }

Configuration examples ​

SQL Server with Windows Authentication:

{
  "ServerName": "PROD-SQL-CLUSTER",
  "ConnectionString": "Server=PROD-SQL-CLUSTER;Database=ProductionDB;Integrated Security=True;MultiSubnetFailover=True;TrustServerCertificate=true;"
}

SQL Server with SQL authentication:

{
  "ServerName": "DEV-SQL-01",
  "ConnectionString": "Server=DEV-SQL-01;Database=DevelopmentDB;User Id=dev_user;Password=dev_password;TrustServerCertificate=true;"
}

PostgreSQL:

{
  "ServerName": "pg-host",
  "ConnectionString": "Host=pg-host;Port=5432;Database=mydb;Username=portway;Password=your-password;"
}

MySQL:

{
  "ServerName": "mysql-host",
  "ConnectionString": "Server=mysql-host;Port=3306;Database=mydb;Uid=portway;Pwd=your-password;SslMode=Preferred;"
}

Access control ​

A request must pass both the token and the endpoint environment restrictions.

Token-level restrictions ​

A token lists its environments: * for all, a comma-separated list, or a prefix pattern such as pro*:

{
  "Username": "api-user",
  "Token": "your-token-here",
  "AllowedEnvironments": "prod,dev"
}

Endpoint-level restrictions ​

An endpoint lists the environments it serves:

{
  "DatabaseObjectName": "ServiceRequests",
  "AllowedEnvironments": ["prod"]
}

Per-environment authentication ​

An Authentication block in the environment's settings.json adds API key, Basic, Bearer, JWT or HMAC authentication for that environment:

{
  "ServerName": "PROD-SQL",
  "ConnectionString": "...",
  "Authentication": {
    "Enabled": true,
    "Methods": [
      {
        "Type": "ApiKey",
        "Name": "X-Custom-Auth",
        "Value": "your-secret-key",
        "In": "Header"
      }
    ]
  }
}

With "Encrypt": false in its settings.json, an environment stays plaintext; use it for non-production credentials only.

Requests authenticated by these methods have no Portway token and are refused on endpoints with Tenancy. JWT and HMAC configuration: Environment Authentication.

Azure Key Vault ​

Connection strings and other secrets can be read from Azure Key Vault instead of settings.json:

1. Set the Key Vault URI:

   WindowsLinux

   powershell

   $env:PORTWAY_KEYVAULT_URI = "https://your-keyvault.vault.azure.net/"

   bash

   export PORTWAY_KEYVAULT_URI="https://your-keyvault.vault.azure.net/"

2. Create secrets per environment:

   • {environment}-ConnectionString
   • {environment}-ServerName
   • {environment}-Headers (JSON string)

The secrets are read at startup and used like file-based values.

Network access policy ​

The file environments/network-access-policy.json lists the upstream hosts proxy endpoints may call (SSRF protection). It is created at first start.

{
  "allowedHosts": [
    "localhost",
    "127.0.0.1",
    "api.internal.example.com",
    "*.services.corp"
  ],
  "blockedIpRanges": [
    "10.0.0.0/8",
    "172.16.0.0/12",
    "192.168.0.0/16",
    "169.254.0.0/16"
  ]
}

A proxy request is allowed when the target host matches allowedHosts and no resolved address is in blockedIpRanges.

With only the two default localhost entries in allowedHosts, the machine's host name and interface addresses are added at startup. Explicit entries disable this.

Wildcard examples (* does not cross dots):

• *.corp matches api.corp and db.corp
• api.*.corp matches api.v1.corp and api.v2.corp

Troubleshooting ​

Debug logging:

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug"
    }
  }
}

Next steps ​

• Configure SQL Endpoints
• Set up Proxy Endpoints
• Access token management
• Deploy to production