Custom Headers

Custom headers allow you to forward authentication tokens, API keys, and other headers to your target APIs when requests are made through PayGates.

Overview

When creating a PayGate, you can specify custom headers that will be automatically forwarded to your target API along with the request. This enables seamless integration with APIs that require authentication or specific headers.

Features

• Header Forwarding: Automatically forward custom headers to target APIs

• Security Validation: Input validation prevents header injection attacks

• Flexible Configuration: Support for any HTTP header name/value pairs

• Encrypted Storage: Headers are encrypted at rest in the database

Usage

Creating PayGates with Custom Headers

{
  "targetUrl": "https://api.example.com/data",
  "method": "GET", 
  "price": "0.01",
  "paymentAddress": "0xYOUR_ADDRESS",
  "customHeaders": {
    "X-API-Key": "your-secret-api-key",
    "Authorization": "Bearer your-token",
    "Content-Type": "application/json",
    "X-Client-ID": "sigwei-proxy"
  }
}

Updating Custom Headers

{
  "customHeaders": {
    "X-API-Key": "updated-api-key",
    "User-Agent": "Sigwei-Client/1.0"
  }
}

Security Features

Input Validation

All custom headers are validated to prevent security vulnerabilities:

• Header Name Validation: Must contain only letters, numbers, hyphens, and underscores

• CRLF Injection Prevention: Blocks carriage return/line feed characters

• Length Limits: Header names limited to 100 characters, values to 1000 characters

• Control Character Filtering: Blocks dangerous control characters and Unicode sequences

Forbidden Prefixes

Certain header prefixes are forbidden to prevent conflicts with system headers:

• auth* - Authentication headers

• cookie* - Cookie headers

• x-payment* - Payment system headers

• authorization* - Authorization headers

• x-auth* - Authentication headers

• session* - Session headers

• token* - Token headers

System Header Protection

The following system headers are automatically added by Sigwei and cannot be overridden:

Payment Headers (Always Present):

• X-Payment - Base64-encoded payment authorization data

• X-Payment-Response - Base64-encoded settlement response from blockchain

Authentication Headers (Mode-Specific):

• Sigwei-Auth-Signature - HMAC signature (HMAC mode only)

• Sigwei-Secret - Shared secret (Plaintext mode only)

These headers ensure secure, authenticated communication between Sigwei and your target server.

Limits

• Maximum Headers: 50 custom headers per PayGate

• Header Name Length: Maximum 100 characters

• Header Value Length: Maximum 1000 characters

• Total Size: No enforced limit on total payload size

Examples

API Key Authentication

{
  "targetUrl": "https://api.weatherservice.com/current",
  "method": "GET",
  "customHeaders": {
    "X-API-Key": "weather-api-key-123"
  }
}

Bearer Token Authentication

{
  "targetUrl": "https://api.github.com/user/repos", 
  "method": "GET",
  "customHeaders": {
    "Authorization": "Bearer github_pat_123...",
    "Accept": "application/vnd.github.v3+json"
  }
}

Multiple Headers for Complex APIs

{
  "targetUrl": "https://enterprise-api.example.com/data",
  "method": "POST",
  "customHeaders": {
    "X-API-Key": "enterprise-key",
    "X-Client-ID": "sigwei-integration",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-Request-ID": "req-123",
    "User-Agent": "Sigwei-Proxy/1.0"
  }
}

Updating Custom Headers

Custom headers can be updated after PayGate creation using the update API:

# Update existing PayGate with new headers
PUT /api/v1/paygates/{id}
{
  "customHeaders": {
    "X-API-Key": "updated-api-key",
    "X-Client-ID": "new-client-id",
    "Authorization": "Bearer updated-token"
  }
}

Note: Updating custom headers completely replaces the existing headers. Include all headers you want to keep in the update request.

Request Flow

1. Client Request: Client makes payment and accesses PayGate URL

2. Header Application: Sigwei applies custom headers to the request

3. System Headers: Sigwei adds authentication headers if configured

4. Proxy Request: Request forwarded to target API with all headers

5. Response: Target API response returned to client

Error Handling

If custom headers fail validation, PayGate creation/update will return a validation error:

{
  "error": {
    "type": "validation", 
    "code": "VALIDATION_ERROR",
    "message": "Header name contains invalid characters"
  }
}

Common validation errors:

• Header name contains invalid characters

• Header value contains CRLF injection attempts

• Header name/value exceeds length limits

• Too many headers (over 50)

• Forbidden header prefix used

Best Practices

Security

• Never include sensitive secrets in header values visible to clients

• Use HMAC authentication mode for additional security

• Regularly rotate API keys and tokens

• Monitor for validation failures that may indicate attacks

Performance

• Keep header values concise to minimize request overhead

• Remove unused headers to reduce payload size

• Use caching-friendly headers when appropriate

Reliability

• Test header forwarding with target APIs before production

• Handle authentication failures gracefully in your target API

• Monitor PayGate access patterns for anomalies