DocumentationJourney OptimizerJourney Optimizer Guide

Configure OAuth 2.0 authentication custom-channel-oauth2

Last update: October 12, 2026

CREATED FOR:

  • Experienced
  • Admin

On this page: Learn how to configure OAuth 2.0 authentication for custom channels in Adobe Journey Optimizer, including the token request payload, credential paths, token extraction, and token location in delivery requests.

style
shade-box

When you select OAuth 2.0 as the authentication type while creating a custom channel, configure the token request that Adobe Journey Optimizer uses to retrieve an access token from your authorization server.

Journey Optimizer sends the token request using the endpoint, method, request, and policy configuration. It then extracts the access token from the response using tokenPath and adds it to the delivery request using locationConfig.

The OAuth 2.0 authentication payload configures the request to the token endpoint. It is separate from the message payload sent to your custom channel delivery endpoint.

Configure the token request token-request

Use the following examples to configure your token request. Replace the example endpoint and credential values with those required by your authorization server. The headers and queryParams entries in the examples are optional: remove them if your token endpoint does not require them, and remove the matching entries from credentialPaths.

Form body example form-body-example

Use a form payload when the token endpoint expects form fields such as grant_type, client_id, or client_secret.

{
  "type": "oauth2",
  "endpoint": {
    "uri": "https://auth.example.com/oauth/token"
  },
  "method": "post",
  "request": {
    "headers": [
      {
        "key": "sampleHeaderKey",
        "value": "sampleHeaderValue"
      }
    ],
    "queryParams": [
      {
        "key": "sampleQueryParamKey",
        "value": "sampleQueryParamValue"
      }
    ],
    "payload": {
      "type": "form",
      "content": [
        {
          "key": "grant_type",
          "value": "client_credentials"
        },
        {
          "key": "client_id",
          "value": "your-client-id"
        },
        {
          "key": "client_secret",
          "value": "your-client-secret"
        }
      ],
      "includeNullValues": false
    }
  },
  "response": {
    "type": "json"
  },
  "policy": {
    "timeoutInMilliseconds": 30000,
    "cache": {
      "enabled": true,
      "ttlInSeconds": 300
    },
    "retry": {
      "enabled": false,
      "maxRetryCount": 3
    }
  },
  "credentialPaths": [
    "header.sampleHeaderKey",
    "queryParam.sampleQueryParamKey",
    "payload.client_id",
    "payload.client_secret"
  ],
  "tokenPath": "access_token",
  "locationConfig": {
    "key": "Authorization",
    "location": "header"
  }
}

For a form payload, each credential path uses the form field key, for example, payload.client_secret. Do not include content or array indexes in the credential path.

JSON body example json-body-example

Use a json payload when the token endpoint expects a JSON request body.

{
  "type": "oauth2",
  "endpoint": {
    "uri": "https://auth.example.com/oauth/token"
  },
  "method": "post",
  "request": {
    "headers": [
      {
        "key": "sampleHeaderKey",
        "value": "sampleHeaderValue"
      }
    ],
    "queryParams": [
      {
        "key": "sampleQueryParamKey",
        "value": "sampleQueryParamValue"
      }
    ],
    "payload": {
      "type": "json",
      "content": {
        "grant_type": "client_credentials",
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      },
      "includeNullValues": false
    }
  },
  "response": {
    "type": "json"
  },
  "policy": {
    "timeoutInMilliseconds": 30000,
    "cache": {
      "enabled": true,
      "ttlInSeconds": 300
    },
    "retry": {
      "enabled": false,
      "maxRetryCount": 3
    }
  },
  "credentialPaths": [
    "header.sampleHeaderKey",
    "queryParam.sampleQueryParamKey",
    "payload.client_id",
    "payload.client_secret"
  ],
  "tokenPath": "access_token",
  "locationConfig": {
    "key": "Authorization",
    "location": "header"
  }
}

OAuth 2.0 fields oauth2-fields

Field
Description
type
Must be oauth2.
endpoint.uri
HTTPS URL of the OAuth 2.0 token endpoint.
method
HTTP method used to call the token endpoint. Use post for token requests.
request.headers
Optional headers sent to the token endpoint.
request.queryParams
Optional query parameters appended to the token endpoint URL.
request.payload
Token request body. Supports form and json payloads.
request.payload.includeNullValues
Defines whether fields with a null value are included in the token request body.
response.type
Response format. Use json when the token endpoint returns a JSON response.
policy.timeoutInMilliseconds
Maximum time to wait for the token endpoint response.
policy.cache
Defines whether the OAuth token is cached and for how long.
policy.retry
Optional retry configuration for token endpoint failures.
credentialPaths
Paths to request fields that contain credentials. These fields are treated as credentials and can be managed securely.
tokenPath
Dot-separated path to the access token in the OAuth response, for example, access_token or data.access_token.
locationConfig
Defines where the retrieved token is added to the delivery request.
locationConfig.key
Name of the header or query parameter that carries the token, for example, Authorization.
locationConfig.location
Where the token is added: header or queryParam.

When token caching is enabled, Journey Optimizer reuses the OAuth token for the configured cache duration instead of calling the token endpoint for every delivery request.

Identify credential fields credential-paths

Use credentialPaths to identify which request fields contain credentials. If a header or query parameter contains a credential, include its path as well as any credential paths in the request body. The examples above identify the sample header and query parameter values as credentials; adjust this list to match your request.

Prefix
Used for
Example
header.
Credential passed in request headers.
header.sampleHeaderKey
queryParam.
Credential passed in query parameters.
queryParam.sampleQueryParamKey
payload.
Credential passed in the request body.
payload.client_secret

Apply the following rules:

  • Paths must start with header, queryParam, or payload and use dots as separators.
  • For form payloads, use payload.<formFieldKey>.
  • For json payloads, use the JSON object path, such as payload.client_id or payload.credentials.client_secret. Do not include content in the path.
  • Empty path segments are not supported. For example, payload..client_id is invalid.

For a nested JSON body, use dot notation as shown in this configuration excerpt:

{
  "request": {
    "payload": {
      "type": "json",
      "content": {
        "credentials": {
          "client_id": "your-client-id",
          "client_secret": "your-client-secret"
        }
      },
      "includeNullValues": false
    }
  },
  "credentialPaths": [
    "payload.credentials.client_id",
    "payload.credentials.client_secret"
  ]
}

Extract the access token token-path

tokenPath defines where the access token is located in the OAuth 2.0 token response.

For the following response, set tokenPath to access_token:

{
  "access_token": "example-access-token",
  "token_type": "Bearer",
  "expires_in": 3600
}

For a nested response, set tokenPath to data.access_token:

{
  "data": {
    "access_token": "example-access-token"
  }
}

Add the token to delivery requests token-location

locationConfig defines where Journey Optimizer adds the retrieved token when calling the custom channel delivery endpoint.

To send the token in the Authorization header, use:

{
  "locationConfig": {
    "key": "Authorization",
    "location": "header"
  }
}
Location
Description
header
Adds the token as an HTTP header.
queryParam
Adds the token as a query parameter.

Limits and validation rules limits

Field
Limit
endpoint.uri
Must be an absolute HTTPS URL with a non-empty host. Maximum length: 2048 characters.
policy.timeoutInMilliseconds
Minimum: 300 ms. Maximum: 60000 ms.
policy.cache.ttlInSeconds
Applies when cache is enabled. Minimum: 300 seconds. Maximum: 3600 seconds.
request.headers
Maximum 50 headers. Header key length: 1-100 characters. Header value maximum: 8192 characters.
request.queryParams
Maximum 50 query parameters. Query parameter key length: 1-100 characters. Query parameter value maximum: 8192 characters.
request.payload.type=form
Maximum 50 form fields. Form key length: 1-100 characters. Duplicate form keys are not allowed.
Credential values
1-1024 characters.
tokenPath
Must be a valid dot-separated path. An empty value is allowed only when the entire response is the token.
credentialPaths
Must start with header, queryParam, or payload and use dots as separators.

Next steps next-steps

AI Knowledge Reference

This section contains structured knowledge intended to support interpretation, retrieval, and question answering related to this topic.

For complete understanding, this information should be combined with the documentation on this page. Neither source is intended to stand alone; the page describes the feature, while this section provides additional context that helps disambiguate terminology, intent, applicability, and constraints.

  • TL;DR: Configure OAuth 2.0 authentication for a custom channel by defining the token endpoint request, identifying credential fields, extracting the access token from the response, and specifying where to add it to delivery requests.

Intents:

  • Configure OAuth 2.0 authentication when creating a custom channel or managing API credentials
  • Choose a form or JSON body for the token endpoint request
  • Identify credential fields in headers, query parameters, and request bodies
  • Extract an access token from a top-level or nested response field
  • Add the retrieved token to a delivery request header or query parameter
  • Understand token caching and authentication configuration limits

Glossary:

  • Token endpoint: The authorization server endpoint that Journey Optimizer calls to retrieve an access token
  • Authentication payload: The configuration of the OAuth 2.0 token request, separate from the message payload sent to the delivery endpoint (product-specific)
  • Credential paths: The paths identifying request fields that contain credentials, configured through credentialPaths (product-specific)
  • Token path: The dot-separated path to the access token in the token endpoint response, configured through tokenPath (product-specific)
  • Token location configuration: The delivery request header or query parameter to which the retrieved token is added, configured through locationConfig (product-specific)

Guardrails:

  • Set the authentication configuration type to oauth2 and use post for token requests.
  • The token endpoint must be an absolute HTTPS URL with a non-empty host and a maximum length of 2048 characters.
  • Token request bodies support form and json payloads; choose the format expected by your authorization server.
  • Credential paths must start with header, queryParam, or payload, use dots as separators, and contain no empty path segments.
  • Form credential paths use the form field key. JSON credential paths use the JSON object path. Do not include content or form array indexes in credential paths.
  • Supported token locations are header and queryParam.
  • The token endpoint timeout must be between 300 and 60000 milliseconds.
  • When token caching is enabled, the cache duration must be between 300 and 3600 seconds. Journey Optimizer reuses the token for the configured duration instead of retrieving a token for every delivery request.
  • Credential values must contain between 1 and 1024 characters.
  • An empty tokenPath is allowed only when the entire response is the token.

Terminology:

  • Canonical name: OAuth 2.0 authentication - variants: OAuth 2.0 authentication payload, OAuth token request configuration
  • Do not confuse: “authentication payload” (configuration for retrieving an access token) with “message payload” (content sent to the custom channel delivery endpoint)
  • Do not confuse: credentialPaths (credential fields in the token request) with tokenPath (access token field in the token response)
  • Do not confuse: request.headers and request.queryParams (values sent to the token endpoint) with locationConfig (where the retrieved token is added to delivery requests)

FAQ:

  • Q: When should I use a form or JSON payload? - Use form when the token endpoint expects form fields, and json when it expects a JSON request body.
  • Q: How do I identify a client secret in a form body? - Use the form field key, for example, payload.client_secret, without content or an array index.
  • Q: How do I identify credentials in a nested JSON body? - Use dot notation, for example, payload.credentials.client_secret.
  • Q: How do I extract a token from a nested response? - Set tokenPath to the response field path, for example, data.access_token.
  • Q: Where can Journey Optimizer add the token to delivery requests? - Set locationConfig.location to header or queryParam and locationConfig.key to the header or query parameter name.
  • Q: Does Journey Optimizer retrieve a token for every delivery request? - When caching is enabled, it reuses the token for the configured cache duration.
recommendation-more-help
journey-optimizer-help