[Extensible policy](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/reference-overview-policy.md.txt#policy-types)

*This page
applies to **Apigee** and **Apigee hybrid**.*


*View [Apigee Edge](https://docs.apigee.com/api-platform/get-started/what-apigee-edge) documentation.*
![](https://fonts.gstatic.com/s/i/googlematerialicons/help/v13/gm_grey-24dp/1x/gm_help_gm_grey_24dp.png)

The ServiceCallout policy lets you call to another service from your API proxy flow. You
can make callouts to either an external service (such as an external RESTful service endpoint) or
internal services (such as an API proxy in the same organization and environment).

This policy is an *Extensible policy* and use of this policy might have cost or
utilization implications, depending on your Apigee license. For information on policy types
and usage implications, see
[Policy types](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/reference-overview-policy.md.txt#policy-types).

- In an external use case, you make a callout to a third-party API that's external to your proxy. The response from the third-party API is parsed and inserted in your API's response message, enriching and *mashing up* the data for app end users. You can also make a request using the ServiceCallout policy in the request flow, then pass the information in the response to the TargetEndpoint of the API proxy.
- In another use case, you call a proxy that's in the same organization and environment as the one you're calling from. For example, you might find this useful when you have a proxy that offers some discrete low-level functionality that one or more other proxies will consume. For example, a proxy that exposes create/read/update/delete operations with a backend data store could be the target proxy for multiple other proxies that expose the data to clients.

The policy supports requests over HTTP and HTTPS.

### Samples

### Local call to an internal proxy

```
<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>
```

This example creates a callout to a local API proxy (that is, one in the same organization
and environment) called `data-manager`, specifying its proxy endpoint whose name
is `default`.

### URL as a variable

```
<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>
```

This example uses a variable in the URL to dynamically populate the URL of the target. The
protocol portion of the URL, `http://`, cannot be specified by a
variable. Also, you must use separate variables for the domain portion of the URL and
for the rest of the URL.

### Google geocoding / define request

```
<ServiceCallout name="ServiceCallout-GeocodingRequest1">
    <DisplayName>Inline request message</DisplayName>
    <Request variable="authenticationRequest">
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
          <QueryParam name="region">{request.queryparam.country}</QueryParam>
          <QueryParam name="sensor">false</QueryParam>
        </QueryParams>
      </Set>
    </Request>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>
```

Instead of using a policy such as the [AssignMessage policy](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/assign-message-policy.md.txt) to create the request object, you can
define it directly in the ServiceCallout policy. In this example, the ServiceCallout policy
sets the values of three query parameters passed to the external service. You can create an
entire request message in the ServiceCallout policy that specifies a payload, encoding type
such as `application/xml`,
headers, form parameters, etc.

Here's another example where the request is formed before reaching the ServiceCallout
policy.

```
<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>
```

The content of the request message is extracted from a variable called
`GeocodingRequest` (which could be
populated, for example, by an AssignMessage policy). The response message is assigned to the
variable called `GeocodingResponse`, where it is a
available to be parsed by an [ExtractVariables policy](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/extract-variables-policy.md.txt) or by custom code written in JavaScript
or Java. The policy waits 30 seconds for the response from the Google Geocoding API before
timing out.

### Call target servers

```
<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout">
    <DisplayName>service-callout</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>myResponse</Response>
    <HTTPTargetConnection>
        <LoadBalancer>
            <Algorithm>RoundRobin</Algorithm>
            <Server name="httpbin"/>
            <Server name="yahoo"/>
        </LoadBalancer>
        <Path>/get</Path>
    </HTTPTargetConnection>
</ServiceCallout>
```

This policy uses the LoadBalancer attribute to call target servers and do load balancing
across them. In this example, load is distributed across two target servers named `httpbin`
and `yahoo`. For information about setting up Target Servers for your proxy and configuring
load balancing, see [Load balancing across
backend servers](https://docs.cloud.google.com/apigee/docs/api-platform/deploy/load-balancing-across-backend-servers).

*** ** * ** ***

> [!NOTE]
> **Note:** If you are using Apigee hybrid v1.14 or newer and your organization is entitled to use the [`Enhanced per-environment proxy limits`](https://docs.cloud.google.com/apigee/docs/hybrid/v1.14/enhanced-proxy-limits.md.txt) feature, you must set the [`enhanceProxyLimits`](https://docs.cloud.google.com/apigee/docs/hybrid/v1.14/config-prop-ref.md.txt#enhanceproxylimits) property to `true` in your `overrides.yaml` file in order to use the ServiceCallout policy.

## About the ServiceCallout policy

There are many scenarios where you can use a ServiceCallout policy in your API proxy. For
example, you can configure an API proxy to make calls to an external service to deliver
geolocation data, customer reviews, items from a partner's retail catalog, and so on.

A callout is typically used with two other policies: AssignMessage and ExtractVariables.

- **Request**: AssignMessage populates the request message sent to the remote service.
- **Response**: ExtractVariables parses the response and extracts specific
  content.

  > [!NOTE]
  > **Note:** The request and response message headers in a ServiceCallout are already available as variables, as described in the [Flow
  > Variables](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy#flowvariables) section. You do not need to extract those with the ExtractVariables policy.

The typical ServiceCallout policy composition involves:

1. [AssignMessage policy](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/assign-message-policy.md.txt): Creates a request message, populates HTTP headers, query parameters, sets the HTTP verb, etc.
2. ServiceCallout policy: References a message created by the AssignMessage
   policy, defines a target URL for the external call, and defines a name for the response object
   that the target service returns.

   For improved performance, you can also cache ServiceCallout responses, as described in
   [How can I store the results of the ServiceCallout policy in cache? and later, retrieve it from cache?](https://discuss.google.dev/t/how-can-i-store-the-results-of-the-servicecallout-policy-in-cache-and-later-retrieve-it-from-cache/10944.html)
3. [ExtractVariables policy](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/extract-variables-policy.md.txt): Typically defines a JSONPath or XPath expression that parses the message generated by the ServiceCallout. The policy then sets variables containing the values parsed from the ServiceCallout response.

> [!NOTE]
> **Note:** An alternative approach to ServiceCallout is an HTTPClient written in JavaScript using the [JavaScript object model](https://docs.cloud.google.com/apigee/docs/api-platform/reference/javascript-object-model.md.txt).

## Custom error handling

> [!NOTE]
> **Sample:** **Learn by doing!**   
> This [Learn Apigee](https://github.com/apigee/api-platform-samples/tree/master/learn-edge/service-callout-2) example shows you how to check the HTTP code in a ServiceCallout response and throw a custom exception based on the value of the code. The example returns a custom error message when the target service returns a `404` status. Just clone the repository and follow the instructions in that topic. The example illustrates a common pattern for handling ServiceCallout errors.

## Element reference

Following are elements and attributes you can configure on this policy:

```
<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Remove>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleAccessToken>
            <Scopes>
              <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
            </Scopes>
            <LifetimeInSeconds ref="{variable}">3600</LifetimeInSeconds>
          </GoogleAccessToken>
        </Authentication>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleIDToken>
            <Audience ref="{variable}" useTargetUrl="BOOLEAN">{hostname}</Audience>
            <IncludeEmail ref="{variable}">true</IncludeEmail>
          </GoogleIDToken>
        </Authentication>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>
```

## \<ServiceCallout\> attributes

```
<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
```

The following table describes attributes that are common to all policy parent elements:

| Attribute | Description | Default | Presence |
|---|---|---|---|
| `name` | The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name. | N/A | Required |
| `continueOnError` | Set to `false` to return an error when a policy fails. This is expected behavior for most policies. Set to `true` to have flow execution continue even after a policy fails. See also: - [Fault rules are triggered ONLY in an error state (about continueOnError)](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/fault-handling.md.txt#multiplefaultrulesandexecutionlogic-faultrulesaretriggeredonlyinanerrorstateaboutcontinueonerror) - [Handling faults within the current flow](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/fault-handling.md.txt#continueonerror) | false | Optional |
| `enabled` | Set to `true` to enforce the policy. Set to `false` to *turn off* the policy. The policy will not be enforced even if it remains attached to a flow. | true | Optional |
| `async` | This attribute is deprecated. | false | Deprecated |

## \<DisplayName\> element

Use in addition to the `name` attribute to label the policy in the
management UI proxy editor with a different, natural-language name.

```
<DisplayName>Policy Display Name</DisplayName>
```

| Default | N/A If you omit this element, the value of the policy's `name` attribute is used. |
| Presence | Optional |
| Type | String |
|---|---|

## \<Request\> element

Specifies the variable containing the request message that gets sent from the API proxy to the
other service. The variable can be created by a previous policy in the flow, or you can create it
inline in the ServiceCallout policy.

```
<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>
```

The syntax for the \<Remove\>, \<Copy\>, \<Add\>, and \<Set\> tags is the same as for the
[AssignMessage
policy](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/assign-message-policy).

> [!NOTE]
> The sub-elements of `<Set>` and `<Add>` support the variable string substitution feature called [message templating](https://docs.cloud.google.com/apigee/docs/api-platform/reference/message-template-intro.md.txt).

The policy returns an error if the request message cannot be resolved or is of an invalid
request message type.

In the simplest example, you pass a variable containing the request message that was populated
earlier in the flow of the API proxy:

```
<Request clearPayload="true" variable="myRequest"/>
```

Or you can populate the request message sent to the external service in the ServiceCallout policy itself:

```
<Request>
  <Set>
    <Headers>
      <Header name="Accept">application/json</Header>
    </Headers>
    <Verb>POST</Verb>
    <Payload contentType="application/json">{"message":"my test message"}</Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
```

|---|---|
| **Default** | If you omit the Request element, or any of its attributes, Apigee assigns the following **default values** : \<Request clearPayload="true" variable="servicecallout.request"/\> Let's look at what these default values mean. First, `clearPayload=true` means that a new request object is created each time the ServiceCallout policy executes. This means that the request and the request URI path are never reused. Second, the default variable name, `servicecallout.request`, is a reserved name that is assigned to the request if you do not supply a name. It's important to know about this default name if you are using [data masking](https://docs.cloud.google.com/apigee/docs/api-platform/security/data-masking.md.txt) -- if you omit the variable name, you need to add `servicecallout.request` to your mask configuration. For example, if you wanted to mask the Authorization header so that it does not appear in Debug sessions, you would add the following to your masking configuration to capture the default name: `servicecallout.request.header.Authorization`. |
| **Presence** | Optional. |
| **Type** | N/A |

### Attributes

| Attribute | Description | Default | Presence |
|---|---|---|---|
| variable | Name of the variable that will contain the request message. | `servicecallout.request` | Optional |
| clearPayload | If `true`, the variable containing the request message is cleared after the request is sent to the HTTP target to free up the memory used by the request message. Set the clearPayload option to false only if the request message is required after the ServiceCallout is executed. | true | Optional |

### \<Request\>/\<IgnoreUnresolvedVariables\> element

When set to true, the policy
ignores any unresolved variable error in the request.

```
<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
```

|---|---|
| **Default** | false |
| **Presence** | Optional |
| **Type** | Boolean |

## \<Response\> element

Include this element when the API proxy logic requires the response from the remote call for
further processing.

When this element is present, it specifies the name of the variable that will contain the
response message received from the external service. The response from the target is assigned to
the variable only when the entire response is read successfully by the policy. If the remote call
fails for any reason, the policy returns an error.

If this element is omitted, the API proxy does not wait for a response; API Proxy flow
execution continues with any subsequent flow steps. Also, to state the obvious, with no
`Response` element, the response from the target is not available for processing by
subsequent steps, and there is no way for the proxy flow to detect a failure in the remote call.
A common use for omitting the `Response` element when using ServiceCallout: to log
messages to an external system.

```
 <Response>calloutResponse</Response>
```

|---|---|
| **Default** | NA |
| **Presence** | Optional |
| **Type** | String |

## \<Timeout\> element

The time in milliseconds that the ServiceCallout policy will wait for a response from the
target. You cannot set this value dynamically at runtime. If the ServiceCallout hits a timeout,
an HTTP 500 is returned, the policy fails, and the API proxy goes into an error state, as
described in [Handling faults](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/fault-handling.md.txt).

```
<Timeout>30000</Timeout>
```

|---|---|
| **Default** | 55000 milliseconds (55 seconds), the default HTTP timeout setting for Apigee |
| **Presence** | Optional |
| **Type** | Integer |

## \<HTTPTargetConnection\> element

Provides transport details such as URL, TLS/SSL, and HTTP properties. See the
`<TargetEndpoint>` configuration reference.

> [!NOTE]
> **Note:** You can use flow variables to construct the URL in an `<HttpTargetConnection>` element.

```
<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>
```

|---|---|
| **Default** | N/A |
| **Presence** | Required |
| **Type** | N/A |

### \<HTTPTargetConnection\>/\<Authentication\> element

> [!NOTE]
> **Apigee hybrid users:** If you are using Apigee hybrid, note that this feature is only supported for Apigee hybrid v1.6.x and later versions.


Generates [Google OAuth 2.0](https://developers.google.com/identity/protocols/oauth2)
or Google-issued [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) tokens
to make authenticated calls to Google services and custom services running
on certain Google Cloud products, such as [Cloud Functions](https://cloud.google.com/functions) and
[Cloud Run](https://cloud.google.com/run).
Use of this element requires setup and deployment steps described in
[Using Google authentication](https://docs.cloud.google.com/apigee/docs/api-platform/security/google-auth/overview.md.txt). With
proper setup, the policy creates an authentication token for you and adds it to the service request.

The child elements, `GoogleAccessToken` and `GoogleIDToken`, let you
configure the policy to generate either Google OAuth or OpenID Connect tokens. You
need to pick one of these child elements depending on the type of service you wish to call.


The ServiceCallout policy only supports calling HTTP-based services.

|---|---|
| **Default** | N/A |
| **Required?** | Optional. |
| **Type** | Complex type |
| **Parent Element** | [`<HTTPTargetConnection>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#httptargetconnection) |
| **Child Elements** | [`<HeaderName>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#headername) [`<GoogleAccessToken>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#googleaccesstoken) [`<GoogleIDToken>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#googleidtoken) |

The `Authentication` element uses the following syntax:

### Syntax

```
<ServiceCallout>
...
  <HTTPTargetConnection>
    <Authentication>
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
          ...
        </Scopes>
        <!-- NOTE: The default value for LifetimeInSeconds is 3600. Change the default only
        if you want to limit the risk of leaked access tokens or improve performance. -->
        <LifetimeInSeconds ref="{variable}">INTEGER</LifetimeInSeconds>
      </GoogleAccessToken>

    --OR--
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
      </GoogleIDToken>
    </Authentication>
  </HTTPTargetConnection>
</ServiceCallout>
```

### Using GoogleAccessToken

The following example shows the `GoogleAccessToken` element:

```
<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>
```

### Using GoogleIDToken

The following example shows the `GoogleIDToken` element:

```
<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>false</IncludeEmail>
  </GoogleIDToken>
</Authentication>
```

### Using HeaderName

The following example shows the `HeaderName` element:

```
  <Authentication>
    <HeaderName>X-Serverless-Authorization</HeaderName>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
    </GoogleAccessToken>
  </Authentication>
```

### Using LifetimeInSeconds

The following example shows the `HeaderName` element:

```
  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
      <LifetimeInSeconds ref="variable">3600</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>
```

#### Attributes


None.

#### HeaderName child element

By default, when an Authentication configuration is present, Apigee generates a bearer
token and injects it into the `Authorization` header in the message sent to the target system.
The `HeaderName` element allows you to specify the name of a different header
to hold that bearer token. This feature is particularly useful when the target is a Cloud Run
service that uses the `X-Serverless-Authorization` header. The `Authorization` header,
if present, is left unmodified and also sent in the request.

|---|---|
| **Default** | N/A |
| **Required?** | No |
| **Type** | String |
| **Parent Element** | [`<Authentication>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#authentication) |
| **Child Elements** | None |

The `HeaderName` element uses the following syntax:

### Syntax

```
<ServiceCallout>
...
  <Authentication>
    <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
    <GoogleAccessToken>
      ...
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>
```

### With static string

In this example, the generated bearer token is added, by default, to a header named `X-Serverless-Authorization`
that is sent to the target system. The `Authorization` header,
if present, is left unmodified and also sent in the request.

```
<Authentication>
  <HeaderName>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>
```

### With variable reference

In this example, the generated bearer token is added, by default, to a header named `X-Serverless-Authorization`
that is sent to the target system. If `my-variable` has a value, that value is used
instead of the default string. The `Authorization` header,
if present, is left unmodified and also sent in the request.

```
<Authentication>
  <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>
```

#### GoogleAccessToken child element

Generates [Google OAuth 2.0](https://developers.google.com/identity/protocols/oauth2) tokens
to make authenticated calls to Google services. Google OAuth tokens can be used to call many kinds of Google services, such as
[Cloud Logging](https://cloud.google.com/logging) and
[Secret Manager](https://cloud.google.com/secret-manager).

|---|---|
| **Default** | N/A |
| **Required?** | Either the `GoogleAccessToken` or `GoogleIDToken` child element must be present. |
| **Type** | String |
| **Parent Element** | [`<Authentication>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#authentication) |
| **Child Elements** | [`<Scopes>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#scopes) [`<LifetimeInSeconds>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#lifetimeinseconds) |

The `GoogleAccessToken` element uses the following syntax:

### Syntax

```
<ServiceCallout>
...
  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>SCOPE_1</Scope>
        ...
      </Scopes>
      <!-- NOTE: The default value for LifetimeInSeconds is 3600. We do not recommend changing
      the default unless you want to limit the risk of leaked access tokens or improve performance. -->
      <LifetimeInSeconds ref="FLOW_VARIABLE">INTEGER</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>
```

### Example 1

The following example shows the `GoogleAccessToken` element:

```
<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>
```

### Example 2

The following example shows how to connect to the secret manager to retrieve a secret
using the ServiceCallout policy.

```
<ServiceCallout name="ServiceCallout-sm">
  <Response>SecretManagerResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>
      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
    </URL>
  </HTTPTargetConnection>
</ServiceCallout>
```

### Example 3

The following example shows how to make a callout to Cloud run from the ServiceCallout policy.

```
<ServiceCallout name="ServiceCallout-CloudRun">
  <Response>CloudRunResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
      </GoogleIDToken>
    </Authentication>
    <URL>https://cloudrun-hostname.a.run.app/test</URL>
  </HTTPTargetConnection>
</ServiceCallout>
```

#### Scopes child element


Identifies the scopes to be included in the OAuth 2.0 access token. For more information, see
[OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/googlescopes). You can add one or more `<Scope>` child elements
under this element.

|---|---|
| **Default** | N/A |
| **Required?** | Required |
| **Type** | String |
| **Parent Element** | [`<GoogleAccessToken>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#googleaccesstoken) |
| **Child Elements** | [`<Scope>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#scope) |

#### Scope child element


Specifies a valid Google API scope. For more information, see
[OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/googlescopes).

|---|---|
| **Default** | N/A |
| **Required?** | At least one value is required. |
| **Type** | String |
| **Parent Element** | [`<Scopes>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#scopes) |
| **Child Elements** | None. |

#### LifetimeInSeconds child element


Specifies the lifetime duration of the access token in seconds.

> [!NOTE]
> **Note:**The default value for LifetimeInSeconds is 3600. We do not recommend changing the default unless you want to limit the risk of leaked access tokens or improve performance.

<br />

|---|---|
| **Default** | 3600 |
| **Required?** | Optional |
| **Type** | Integer |
| **Parent Element** | [`<GoogleAccessToken>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#googleaccesstoken) |
| **Child Elements** | None. |

#### GoogleIDToken child element

Generates Google-issued [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) tokens
to make authenticated calls to Google services.

|---|---|
| **Default** | N/A |
| **Required?** | Either the `GoogleAccessToken` or `GoogleIDToken` child element must be present. |
| **Type** | String |
| **Parent Element** | [`<Authentication>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#authentication) |
| **Child Elements** | [`<Audience>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#audience) [`<IncludeEmail>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#includeemail) |

The `GoogleIDToken` element uses the following syntax:

### Syntax

```
<ServiceCallout>
...
  <Authentication>
    <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
    </GoogleIDToken>
  </Authentication>
</ServiceCallout>
```

### Example 1

The following example shows the `GoogleIDToken` element:

```
<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>true</IncludeEmail>
  </GoogleIDToken>
</Authentication>
```

#### Audience child element


The audience for the generated authentication token, such as the API or account that the
token grants access to.


If the value of `Audience` is empty or the `ref` variable does not resolve to a valid value, and
`useTargetUrl` is `true`, then the URL of the target (excluding any
query parameters) is used as the audience. By default, `useTargetUrl` is `false`.

> [!NOTE]
> **Apigee hybrid users:** If you use Apigee hybrid, note that the `useTargetUrl` attribute is available in Apigee hybrid version 1.8 and later versions.

```
<Audience>explicit-audience-value-here</Audience>

or:

<Audience ref='variable-name-here'/>

or:

<Audience ref='variable-name-here' useTargetUrl='true'/>

or:

<Audience useTargetUrl='true'/>
```

|---|---|
| **Default** | N/A |
| **Required?** | Required |
| **Type** | String |
| **Parent Element** | [`<GoogleIDToken>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#googleidtoken) |
| **Child Elements** | None. |

#### IncludeEmail child element


If set to `true`, the generated authentication token will contain the
service account `email` and `email_verified` claims.

|---|---|
| **Default** | false |
| **Required?** | Optional |
| **Type** | Boolean |
| **Parent Element** | [`<GoogleIDToken>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#googleidtoken) |
| **Child Elements** | None. |

### \<HTTPTargetConnection\>/\<URL\> element

The URL to the service being called:

> [!NOTE]
> The `<URL>` element supports the variable string substitution feature called [message templating](https://docs.cloud.google.com/apigee/docs/api-platform/reference/message-template-intro.md.txt).

```
<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>
```

You can supply part of the URL dynamically with a variable. However, the protocol portion of
the URL, http:// below, cannot be
specified by a variable. In the next example, you use a variable to specify the value of a query
parameter:

```
<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>
```

Or, set a portion of the URL path with a variable:

```
<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>
```

If you want to use a variable to specify the domain and port of the URL, then use one variable
for the domain and port only, and a second variable for any other part of the URL:

```
<URL>http://{request.dom_port}/{request.resourcePath}</URL>
```

|---|---|
| **Default** | N/A |
| **Presence** | Required |
| **Type** | String |

### \<HTTPTargetConnection\>/\<SSLInfo\> element

The TLS/SSL configuration to the backend service. For help on TLS/SSL configuration, see
[Options for configuring TLS](https://docs.cloud.google.com/apigee/docs/api-platform/system-administration/options-configuring-tls.md.txt) and "TLS/SSL TargetEndpoint Configuration"
in [API proxy configuration reference](https://docs.cloud.google.com/apigee/docs/api-platform/reference/api-proxy-configuration-reference.md.txt).

> [!NOTE]
> **Note:** Specify the `KeyStore` name in the `SSLInfo` element as a reference in the form `ref://mykeystoreref`. Using a reference, rather than a direct name or flow variable, is recommended. See [About setting the \<KeyStore\> and \<TrustStore\> elements.](https://docs.cloud.google.com/apigee/docs/api-platform/system-administration/options-configuring-tls.md.txt#about-setting-the-%3Ckeystore%3E-and-%3Ctruststore%3E-elements)

```
<HTTPTargetConnection>
    <URL>https://example.com</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://mykeystoreref</KeyStore>  ## Use of a reference is recommended
        <KeyAlias>myKey</KeyAlias>
        <TrustStore>myTruststore</TrustStore>
        <Ciphers/>
        <Protocols/>
    </SSLInfo>
</HTTPTargetConnection>
```

|---|---|
| **Default** | N/A |
| **Presence** | Optional |
| **Type** | N/A |

### \<HTTPTargetConnection\>/\<Properties\> element

HTTP transport properties to the backend service. For more information, see
[Endpoint properties reference](https://docs.cloud.google.com/apigee/docs/api-platform/reference/endpoint-properties-reference.md.txt).

```
<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <Properties>
        <Property name="allow.http10">true</Property>
        <Property name="request.retain.headers">
          User-Agent,Referer,Accept-Language
        </Property>
    </Properties>
</HTTPTargetConnection>
```

|---|---|
| **Default** | N/A |
| **Presence** | Optional |
| **Type** | N/A |

### \<HTTPTargetConnection\>/\<LoadBalancer\> element

Call one or more target servers and do load balancing on them. See the **Call target
servers** sample in the [Samples section](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#Samples). See also [Load balancing across backend
servers](https://docs.cloud.google.com/apigee/docs/api-platform/deploy/load-balancing-across-backend-servers). See also [Target Endpoint/Server callout](https://discuss.google.dev/t/target-endpoint-server-callout/1743.html) that discusses ways to call target servers from both the ServiceCallout policy and
using Route Rules.

```
<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>
```

|---|---|
| **Default** | N/A |
| **Presence** | Optional |
| **Type** | N/A |

## \<LocalTargetConnection\> element

Specifies a local proxy -- that is, a proxy in the same organization and environment -- as the
target of service callouts.

To further specify the target, use either the [`<APIProxy>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#apiproxy) and [`<ProxyEndpoint>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#proxyendpoint) elements, or the [`<Path>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#localtargetconnection-path) element.

```
<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>
```

|---|---|
| **Default** | N/A |
| **Presence** | Required |
| **Type** | N/A |

### \<LocalTargetConnection\>/\<APIProxy\> element

The name of an API proxy that is the target of a local call. The proxy must be in the same
organization and environment as the proxy making the call.

```
<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>
```

Along with the `<APIProxy>` element, include the
`<ProxyEndpoint>` element to specify the name of the proxy endpoint that should
be targeted for the call.

```
<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection>
```

|---|---|
| **Default** | N/A |
| **Presence** | Required |
| **Type** | String |

### \<LocalTargetConnection\>/\<ProxyEndpoint\> element

The name of the proxy endpoint that should be the target of calls. This is a proxy endpoint in
the API proxy specified with the `<APIProxy>` element.

```
<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>
```

|---|---|
| **Default** | N/A |
| **Presence** | Optional |
| **Type** | N/A |

### \<LocalTargetConnection\>/\<Path\> element

A path to the endpoint that is being targeted. The endpoint must refer to a proxy in the same
organization and environment as the proxy making the call.

Use this instead of a `<APIProxy>/<ProxyEndpoint>` pair when you don't
know -- or can't rely on -- the proxy name. The path might be a reliable target.

```
<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>
```

|---|---|
| **Default** | N/A |
| **Presence** | Optional |
| **Type** | N/A |

## Schemas

> [!NOTE]
> **Sample:** See our [GitHub
> repository](https://github.com/apigee/api-platform-samples/tree/master/schemas/policy) samples for the most recent schemas.

## Flow variables

Flow variables enable dynamic behavior of policies and Flows at runtime, based on HTTP
headers, message content, or Flow context. The following predefined Flow variables are available
after a ServiceCallout policy executes. For more information about Flow variables, see
[Flow variables reference](https://docs.cloud.google.com/apigee/docs/api-platform/reference/variables-reference.md.txt).

ServiceCallouts have their own request and response, and you can access that data through
variables. Because the main message is using the `request.*` and
`response.*` variable prefixes, use the `myrequest.*` and
`calloutResponse.*` prefixes (the defaults in the ServiceCallout configuration) to
get message data specific to the ServiceCallout. The first example in the following table shows
how you'd get HTTP headers in the ServiceCallout.

| Variable | Description |
|---|---|
| Following is an example of getting ServiceCallout request and response headers similar to how you would get headers from the main request and response. `calloutResponse.header.HeaderName` `myRequest.header.HeaderName` where *calloutResponse* is the variable name for the Response in the Service Callout, and *myRequest* is the variable name for the Request. For example: `calloutResponse.header.Content-Length` returns the Content-Length header of the ServiceCallout response. | **Scope** : From the ServiceCallout forward **Type** : String **Permission**: Read/Write A message header in the ServiceCallout request or response. For example, if the API proxy target is http://example.com, and the ServiceCallout target is http://mocktarget.apigee.net, these variables are the headers for the callout to http://mocktarget.apigee.net. |
| `servicecallout.requesturi` | **Scope** : From the ServiceCallout request forward **Type** : String **Permission**: Read/Write The TargetEndpoint URI for a ServiceCallout policy. The URI is the TargetEndpoint URL without the protocol and domain specification. |
| `servicecallout.{policy-name}.target.url` | **Scope** : From the ServiceCallout request forward **Type** : String **Permission**: Read/Write The target URL for a the ServiceCallout. |
| `calloutResponse.content` where `calloutResponse` is the `<Response>`variable name in the ServiceCallout configuration. | **Scope** : From the ServiceCallout response forward **Type** : String **Permission**: Read/Write The response body from the ServiceCallout. |
| `servicecallout.{policy-name}.expectedcn` | **Scope** : From the ServiceCallout request forward **Type** : String **Permission**: Read/Write The expected Common Name of the TargetEndpoint as referred to in a ServiceCallout policy. This is meaningful only when the TargetEndpoint refers to a TLS/SSL endpoint. |
| `servicecallout.{policy-name}.failed` | **Scope** : From the ServiceCallout response forward **Type** : Boolean **Permission**: Read/Write Boolean indicating if the policy succeeded, false, or failed, true. |

## Errors


This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error.
This information is important to know if you are developing fault rules to
handle faults. To learn more, see [What you need to know
about policy errors](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/what-you-need-know-about-policy-errors) and [Handling
faults](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/fault-handling).

### Runtime errors

These errors can occur when the policy executes.

> [!IMPORTANT]
> **Tip:** Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

| Fault code | HTTP status | Cause | Fix |
|---|---|---|---|
| `steps.servicecallout.ExecutionFailed` | `500` | This error can occur when: - The policy is asked to handle input that is malformed or otherwise invalid. - The backend target service returns an error status (by default, `4xx` or `5xx`). | [](https://docs.cloud.google.com/apigee/docs/api-platform/troubleshoot/policies/runtime/service-callout-runtime-errors.md.txt#executionfailed) |
| `steps.servicecallout.RequestVariableNotMessageType` | `500` | The `Request` variable specified in the policy is not of type `Message`. For example, if it's a string or other non-message type, you'll see this error. | [](https://docs.cloud.google.com/apigee/docs/api-platform/troubleshoot/policies/runtime/service-callout-runtime-errors.md.txt#requestvariablenotmessagetype) |
| `steps.servicecallout.RequestVariableNotRequestMessageType` | `500` | The `Request` variable specified in the policy is not of type `RequestMessage`. For example, if it's a Response type, you'll see this error. | [](https://docs.cloud.google.com/apigee/docs/api-platform/troubleshoot/policies/runtime/service-callout-runtime-errors.md.txt#requestvariablenotrequestmessagetype) |
| `googletoken.EmptyIDTokenAudience` | `500` | `<GoogleIDToken>` is enabled but `useTargetUrl` is set to false and no value is provided to `<Audience>` either directly or through reference at the time of error. |   |
| `messaging.adaptors.http.filter.GoogleTokenGenerationFailure` | `500` | This error can happen if the API proxy is configured with the \<Authentication\> element. Possible causes include: - The service account deployed with the proxy: - does not exist in your project - has been disabled - (Apigee hybrid only) has not granted the **roles/iam.serviceAccountTokenCreator** role on the `apigee-runtime` service account. - The `IAMCredentials` API is disabled in the source project of the `apigee-runtime` service account. - The `<GoogleAccessToken>` element is used and one or more invalid scopes are provided. For example, look for typos or empty scopes. - For Apigee hybrid only, check the runtime container's log and search for `GoogleTokenGenerationFailure` to find more detailed error messages that may help with debugging the problem. |   |

### Deployment errors

These errors can occur when you deploy a proxy containing this policy.

> [!IMPORTANT]
> **Tip:** Need help fixing an error? Click in the Fix column for detailed troubleshooting information.

| Error name | Cause | Fix |
|---|---|---|
| `URLMissing` | The `<URL>` element inside `<HTTPTargetConnection>` is missing or empty. | [](https://docs.cloud.google.com/apigee/docs/api-platform/troubleshoot/policies/deployment/service-callout-deployment-errors.md.txt#urlmissing) |
| `ConnectionInfoMissing` | This error happens if the policy does not have an `<HTTPTargetConnection>` or `<LocalTargetConnection>` element. | [](https://docs.cloud.google.com/apigee/docs/api-platform/troubleshoot/policies/deployment/service-callout-deployment-errors.md.txt#connectioninfomissing) |
| `InvalidTimeoutValue` | This error happens if the `<Timeout>` value is negative or zero. | [](https://docs.cloud.google.com/apigee/docs/api-platform/troubleshoot/policies/deployment/service-callout-deployment-errors.md.txt#invalidtimeoutvalue) |
| `FAILED_PRECONDITION` | This error happens if the service account is missing when the proxy is configured with the \<Authentication\> tag. For example: ``` Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service account identity, but one was not provided with the request. ``` |   |
| `PERMISSION_DENIED` | This error happens if there is a permission problem with the service account if the proxy is configured with the \<Authentication\> tag. Possible causes: - The service account does not exist. - The service account was not created in the same Google Cloud project as the Apigee organization. - The deployer does have **iam.serviceAccounts.actAs** permission on the service account. For details, see [About service account permissions](https://docs.cloud.google.com/apigee/docs/api-platform/security/google-auth/overview.md.txt#about-service-account-permissions). |   |

### Fault variables

These variables are set when a runtime error occurs. For more information, see [What you need to know
about policy errors](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/what-you-need-know-about-policy-errors).

| Variables | Where | Example |
|---|---|---|
| `fault.name="fault_name"` | <var translate="no">fault_name</var> is the name of the fault, as listed in the [Runtime errors](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/service-callout-policy.md.txt#runtime-errors) table above. The fault name is the last part of the fault code. | `fault.name = "RequestVariableNotMessageType"` |
| `servicecallout.policy_name.failed` | <var translate="no">policy_name</var> is the user-specified name of the policy that threw the fault. | `servicecallout.SC-GetUserData.failed = true` |

### Example error response

> [!NOTE]
> **Note:** For error handling, the best practice is to trap the `errorcode` part of the error response. Do not rely on the text in the `faultstring`, because it could change.

```
{
   "fault":{
      "detail":{
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]:
            request variable data_str value is not of type Message"
   }
}
```

### Example fault rule

```
<FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>
```

<br />

## Related topics

- Generate or modify messages: [AssignMessage policy](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/assign-message-policy.md.txt)
- Extract variables: [ExtractVariables policy](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/extract-variables-policy.md.txt)
- Variables: [Flow variables reference](https://docs.cloud.google.com/apigee/docs/api-platform/reference/variables-reference.md.txt)
- TLS/SSL configuration
  - [Options for configuring TLS](https://docs.cloud.google.com/apigee/docs/api-platform/system-administration/options-configuring-tls.md.txt)
  - "TLS/SSL TargetEndpoint Configuration" in [API proxy configuration reference](https://docs.cloud.google.com/apigee/docs/api-platform/reference/api-proxy-configuration-reference.md.txt)
- HTTP transport properties: [Endpoint properties reference](https://docs.cloud.google.com/apigee/docs/api-platform/reference/endpoint-properties-reference.md.txt)
- Alternative to ServiceCallout: HTTPClient written in JavaScript, see [JavaScript object model](https://docs.cloud.google.com/apigee/docs/api-platform/reference/javascript-object-model.md.txt).