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.

Token reuse

A token belongs to its credentials, not to the module that fetched it. Every module in the process configured with the same tokenUrl, clientId, clientSecret and scope shares one token, and keeps sharing it across scheduled runs — a run does not start from a cold cache.

This matters for how often your provider sees you. A pipeline scheduled every 15 seconds with a one-hour token makes roughly 24 token requests a day, not 5 760. Token endpoints are commonly rate-limited far more aggressively than the APIs behind them, and that difference is the difference between fitting in the quota and not.

Two consequences worth knowing:

• A 401 invalidates the token for everyone. The next module to need one fetches a fresh token, and the rest pick it up. You will not see each module rediscover the rejection on its own.
• Rotating a secret does not serve a stale token. The cache is keyed on the credentials themselves, so new credentials simply miss and fetch. There is nothing to flush.

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