Environment Authentication

Sometimes the global token system isn't quite the right fit for one environment: perhaps a partner needs an API key, or an upstream system already speaks JWT. Environment-specific authentication lets you handle those cases in that environment's settings.json, with ApiKey, Basic, Bearer, JWT, and HMAC methods available. Sensitive fields you write in plaintext are encrypted to PWENC: format on the next startup, so there is no need to pre-encrypt anything yourself.

If multiple methods are defined, a request is authorised if it satisfies any of them.

Configuration Structure ​

The authentication settings are defined in the Authentication object within settings.json.

File Location ​

/environments/[EnvironmentName]/settings.json

Basic Structure ​

{
  "Authentication": {
    "Enabled": true,
    "OverrideGlobalToken": false,
    "Methods": [
      {
        "Type": "ApiKey",
        "Name": "X-API-Key",
        "Value": "your-secret-key",
        "In": "Header"
      }
    ]
  }
}

Property Reference ​

Supported Authentication Methods ​

1. ApiKey ​

Matches a static value against a header, query parameter, or cookie.

2. Basic ​

Standard HTTP Basic authentication.

3. Bearer ​

Matches a static token in the Authorization: Bearer <token> header.

4. JWT (JSON Web Token) ​

Performs full JWT validation including signature, issuer, and audience.

5. HMAC ​

Validates a request signature generated using a shared secret.

Automatic Encryption ​

When you save a settings.json file with plaintext secrets, Portway detects them on next startup and encrypts them using RSA/AES hybrid encryption.

The following fields are automatically encrypted:

• Value
• Secret
• ClientSecret

Encrypted values are prefixed with PWENC: and are safe to store on disk.

Global Token Fallback ​

By default (OverrideGlobalToken: false), Portway uses the following logic:

1. Try environment-specific authentication.
2. If it succeeds, authorize the request.
3. If it fails, attempt to authorize using a standard Portway Bearer token.
4. If both fail, return 401 Unauthorized.

If OverrideGlobalToken is set to true, only requests that satisfy the environment-specific rules are authorised; global tokens are rejected for that environment.

Security Notes ​

Use cryptographically strong keys for ApiKey and HMAC methods. Rotate credentials periodically. For OAuth2 provider integrations, prefer JWT for full signature validation. Authentication credentials sent via headers are only secure over HTTPS.

Related Topics ​

• Environment Settings - General environment configuration
• API Authentication - Standard Portway token system
• Security Guide - General security practices