Connections Concept

How the pfx-rest component resolves authentication and base URLs through named connections.

Overview

Every pfx-rest endpoint can reference a named connection via the connection parameter. The connection determines:

The base URL for the request
The authentication strategy (none, Basic, JWT, OAuth2)
Optional default headers
Optional re-authentication behavior on specific HTTP error codes

If no connection is specified (or the named connection is not found and failIfNoConnection=false), the component falls back to a default no-auth connection.

Connection Types

REST Public (`rest-public`)

No authentication. Used for accessing public APIs.

Field	Description
`url`	Base URL for all requests
`headers`	Optional default headers sent with every request

REST Basic (`rest-basic`)

HTTP Basic authentication. Credentials are sent with every request.

Field	Default	Description
`url`		Base URL for all requests
`headers`		Optional default headers
`username`		Basic auth username
`password`		Basic auth password
`authRequestHeader`	`Authorization`	Header name for the auth credential
`authRequestHeaderBearer`	`Basic`	Prefix for the header value

REST JWT (`rest-jwt`)

Token-based authentication. A token is obtained from an auth endpoint before the first request and refreshed when it expires.

Field	Default	Description
`url`		Base URL for all requests
`headers`		Optional default headers
`authUrl`		URL of the token endpoint
`username`		Auth username
`password`		Auth password
`authRequestTemplate`	`{"username": "::username","password":"::password"}`	Template body for the token request
`authRequestContentType`	`application/json`	Content type for the token request
`authRequestHeader`		Header name for the token
`authRequestHeaderBearer`	`Bearer`	Prefix for the token header value
`authResponseTokenKey`	`access_token`	JSON key in the auth response containing the token
`authResponseExpirationKey`	`expires_in`	JSON key for token expiration
`authResponseExpirationKeyLocation`		Location of the expiration key (e.g., in a nested object)
`authExpirationMultiplier`	`1`	Multiplier applied to the expiration value
`reAuthOnCodes`		Comma-separated HTTP codes that trigger re-authentication

REST OAuth2 (`rest-oauth2`)

OAuth2 authentication. Similar to JWT but supports client credentials and scope.

Field	Default	Description
`url`		Base URL for all requests
`headers`		Optional default headers
`authUrl`		URL of the token endpoint
`username`		OAuth2 username
`password`		OAuth2 password
`clientId`		OAuth2 client ID
`clientSecret`		OAuth2 client secret
`scope`		OAuth2 scope
`authRequestTemplate`	`{"grant_type": "password","client_id": "::clientId","client_secret": "::clientSecret","username": "::username","password":"::password"}`	Template body for the token request
`authRequestContentType`	`application/x-www-form-urlencoded`	Content type for the token request
`authRequestHeader`		Header name for the token
`authRequestHeaderBearer`	`Bearer`	Prefix for the token header value
`authResponseTokenKey`		JSON key in the auth response containing the token
`authResponseExpirationKey`		JSON key for token expiration
`authResponseExpirationKeyLocation`		Location of the expiration key
`authExpirationMultiplier`		Multiplier applied to the expiration value
`reAuthOnCodes`		Comma-separated HTTP codes that trigger re-authentication

Authentication Template Placeholders

Token-based connections (JWT, OAuth2) use authRequestTemplate with placeholder strings that are resolved at runtime:

Placeholder	Resolved From
`::username`	Connection username
`::password`	Connection password
`::clientId`	Connection clientId (OAuth2 only)
`::clientSecret`	Connection clientSecret (OAuth2 only)
`::scope`	Connection scope (OAuth2 only)

Example: The default OAuth2 template is:

{"grant_type": "password","client_id": "::clientId","client_secret": "::clientSecret","username": "::username","password":"::password"}

At runtime, ::clientId is replaced with the actual clientId value from the connection, and so on.

Re-authentication on Error Codes

For token-based connections (JWT, OAuth2), the reAuthOnCodes field accepts a comma-separated list of HTTP status codes (e.g., 400,401,404). When any of these codes are returned from a request, the component will:

Discard the current token
Request a new token from the auth endpoint
Retry the original request with the new token

This is useful for systems like Salesforce where tokens may be invalidated unexpectedly.

SSL Certificates

When the target API uses a self-signed or custom SSL certificate, the certificate can be configured at the connection level. The component's HTTP client will trust the configured certificate for that connection.

Connection Behavior Parameter

Parameter	Type	Default	Description
`failIfNoConnection`	`boolean`	`false`	When `true`, the component throws an exception if the named connection is not found. When `false` (default), it falls back to a default no-auth connection.

Common Pitfalls

Pitfall	Resolution
Connection name misspelled or not deployed	Enable `failIfNoConnection=true` to get a clear error instead of silent fallback to no-auth
OAuth2 token expires mid-batch	Set `reAuthOnCodes=401` so the component automatically re-authenticates and retries
Wrong `authRequestContentType` for OAuth2	Most OAuth2 providers expect `application/x-www-form-urlencoded` (the default). Check your provider's docs if token requests fail.
Placeholders not replaced in template	Ensure the connection fields (`username`, `password`, `clientId`, etc.) are populated. Unresolved `::placeholder` strings are sent literally.
Base URL missing trailing slash vs. URI having leading slash	Be consistent: if `url` ends with `/api`, set `uri=/v1/resource` (with leading slash). The component concatenates them directly.