HTTP Headers

Headers carry a surprising amount of Portway's conversation with your clients: authentication, content negotiation, request tracking, and service configuration all travel there. This page collects every header Portway reads or writes, so you have one place to look things up.

Required Headers ​

Authentication Header ​

Every API request needs to include authentication:

Authorization: Bearer your_token_here

This applies to every endpoint except /health/live, so it is worth confirming your client attaches the token on each call. Requests that arrive without it receive a 401 Unauthorized response.

Content Type Headers ​

For requests with a body (POST, PUT, PATCH):

Content-Type: application/json
Accept: application/json

Request Headers ​

Standard Headers ​

Custom Headers ​

Environment Headers ​

Internal headers can be automatically added, based on the environment configuration. This means that settings.json in the /environments/{env} folder can append custom headers. For example:

Example from environment settings:

{
  ...
  "Headers": {
    "DatabaseName": "prod",
    "ServerName": "YOUR-APP-SERVER",
    "Origin": "Portway"
  }
}

Response Headers ​

Standard Response Headers ​

Security Headers ​

Portway automatically adds security headers to all responses:

Rate Limiting Headers ​

Content Negotiation ​

Request Headers ​

Accept: application/json
Accept-Language: en-US
Accept-Encoding: gzip, deflate

Response Headers ​

Content-Type: application/json; charset=utf-8
Content-Language: en-US
Content-Encoding: gzip

Compression ​

Portway supports response compression:

Request with compression preference:

Accept-Encoding: br, gzip, deflate

CORS Headers ​

For cross-origin requests:

Proxy Headers ​

When Portway acts as a reverse proxy:

Caching Headers ​

ETag revalidation ​

Every successful GET response under /api carries a strong ETag, computed from the response body:

HTTP/1.1 200 OK
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4..."

When your client sends that value back in If-None-Match and the data hasn't changed, Portway answers with 304 Not Modified and an empty body, saving the transfer entirely:

GET /api/prod/Products?$top=10
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4..."

HTTP/1.1 304 Not Modified

Because the tag is derived from the actual response content, any change in the underlying data produces a new tag and a fresh 200 with the full body. Polling clients benefit the most: a poll loop that sends If-None-Match costs almost nothing while nothing changes.

Response Cache Control ​

Cache-Control: private, max-age=300
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Cache Control Directives ​

Header Size Limits ​

Keep header values concise and use standard headers where possible. Avoid including sensitive data (passwords, connection strings, PII) in headers. Validate and sanitize custom header values. Disable debug headers in production.

Security Considerations ​

Headers to Avoid ​

Common Header Issues ​

Missing Headers ​

# Error: Missing Authorization
GET /api/500/Products
Response: 401 Unauthorized
{
  "error": "Authentication required",
  "clientIp": "0.0.0.0",
  "requestedPath": "/api/500/Products",
  "success": false
}

Invalid Header Values ​

# Error: Invalid content type
POST /api/500/Products
Content-Type: text/plain
Response: 415 Unsupported Media Type
{
  "error": "Content-Type must be application/json"
}

Header Conflicts ​

# Error: Conflicting cache directives
GET /api/500/Products
Cache-Control: no-cache, max-age=3600
Response: 400 Bad Request
{
  "error": "Conflicting cache control directives"
}

Testing Headers ​

Using cURL ​

# Basic request with headers
curl -H "Authorization: Bearer token123" \
     -H "Accept: application/json" \
     https://api.company.com/api/500/Products

# POST with content type
curl -X POST \
     -H "Authorization: Bearer token123" \
     -H "Content-Type: application/json" \
     -d '{"name":"Product"}' \
     https://api.company.com/api/500/Products

Using Postman ​

1. Add headers in the Headers tab
2. Use environment variables for tokens
3. Set up header presets for common requests
4. Use Postman collections for header management

Related Topics ​

• Authentication - Token and authorization headers
• API Overview - General API reference
• Environment Settings - Environment-specific headers
• Security Guide - Security header configuration