Authentication

Every HTTP-shaped and SOAP-shaped module (httpPolling, webhook, http_call, httpRequest, soapPolling, soap_call, soapRequest) accepts the same authentication block for transport authentication. Credentials live in environment variables, never in the YAML.

SOAP services may also require WS-Security UsernameToken. That is configured with wsSecurity, not authentication; see SOAP.

The shape

authentication:
  type: <api-key | bearer | basic | oauth2>
  credentials:
    # type-specific fields

api-key

A key passed either as an HTTP header or a query parameter.

authentication:
  type: api-key
  credentials:
    key: ${SOURCE_API_KEY}
    location: header              # header | query
    headerName: X-Api-Key         # required if location=header
    paramName: api_key            # required if location=query

bearer

The most common HTTP auth flavor — Authorization: Bearer <token>.

authentication:
  type: bearer
  credentials:
    token: ${SOURCE_BEARER_TOKEN}

basic

Sends an Authorization: Basic … header. Credentials are Base64-encoded by Cannectors at request time.

authentication:
  type: basic
  credentials:
    username: ${SOURCE_USERNAME}
    password: ${SOURCE_PASSWORD}

oauth2

OAuth2 client credentials grant. Cannectors acquires a token on first use, caches it, and refreshes automatically before expiry. No manual refresh handling required.

authentication:
  type: oauth2
  credentials:
    tokenUrl: ${OAUTH_TOKEN_URL}
    clientId: ${OAUTH_CLIENT_ID}
    clientSecret: ${OAUTH_CLIENT_SECRET}
    scope: read:orders           # optional, space-separated for multiple

Only the client_credentials grant is supported. For user-delegated flows, fetch a token externally and feed it via bearer.

Per-module overrides

Authentication is per-module — the input, each filter, and the output can all use a different scheme. The 23-auth-basic-bearer-query-key.yaml example uses bearer on input, basic on enrichment, and an API key on output, all in one pipeline.

input:
  type: httpPolling
  authentication:
    type: bearer
    credentials:
      token: ${SOURCE_BEARER_TOKEN}

filters:
  - type: http_call
    authentication:
      type: basic
      credentials:
        username: ${DIR_USERNAME}
        password: ${DIR_PASSWORD}
    …

output:
  type: httpRequest
  authentication:
    type: api-key
    credentials:
      key: ${DEST_API_KEY}
      location: query
      paramName: api_key

Secrets, never in YAML

Credentials are always read from environment variables via the ${VAR} syntax. The runtime substitutes them at startup; the resolved values are never logged. See Environment variables.

Cross-references