---
schema_version: "1"
id: 8d0fd9686a48651d391510b3d539d80760a8c808288a63c0d04772c6771b85d2
title: A2A In-Task Authorization Code Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/1.13/policies-outbound-a2a-intask-authorization-code.md
canonical_url: https://docs.mulesoft.com/gateway/1.13/policies-outbound-a2a-intask-authorization-code
source_site: docs.mulesoft.com
content_type: documentation
content_hash: e1e5a83a7faa39271e3e9556a0472c6ee1517ca964c23761ae0d50b411bcb3d9
description: MuleSoft Documentation Site
release: "1.13"
latest: false
---
---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, a2a, authentication, oauth2, outbound
---

# A2A In-Task Authorization Code Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A In-Task Authorization Code</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Ensures secondary credentials are present for in-task authentication using OAuth 2.0 Authorization Code flow</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.4</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-intask-authorization-code-policy-release-notes">A2A In-Task Authorization Code Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>200 (authentication challenge), 401 (authentication failure)</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The In-Task Authorization Code policy is an outbound policy that ensures secondary credentials are
present for in-task authentication using OAuth 2.0 Authorization Code flow. When requests require
additional authentication beyond the initial connection, this policy:

1.  Detects if a request contains a secondary authentication token at
    `$.params.message.parts[].data.auth_credentials.accessToken`. This policy assumes that all
    requests besides agent card requests require secondary authentication.

2.  If a secondary token is missing, the policy returns an `auth-required` challenge with details of
    where the agent can obtain the token from the OAuth 2.0 authentication provider.

    To learn more about the authentication challenge response, see
    [Challenge Response Format](#challenge-response).

3.  If the token was initially provided or returned from the challenge response, the policy extracts
    the token from the request body.

4.  The policy sets the extracted token in the `Authorization` header and removes the token from the
    request body to prevent token leakage.

    To learn more about token handling, see [Token Handling](#token-handling).

5.  The policy then forwards the request to upstream services.

When the inbound user can be identified, the policy reuses secondary tokens from a token cache. To
learn more about how this policy caches requests, see [Token caching](#token-caching-intask).

> [!NOTE] To ensure agent discovery works uninterrupted, requests to these agent card endpoints
> bypass the policy without authentication:
>
> - `/.well-known/agent-card.json`
>
> - Any path ending in `agent-card.json`

## Configuring Policy Parameters

### Omni Gateway Local Mode

The In-Task Authorization Code policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Secondary Auth Provider</p></div></div></td><td><div><div><p>Name of the OAuth 2.0 identity provider. For example: <code>okta</code>, <code>azure-ad</code>, <code>auth0</code>.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Authorization Endpoint</p></div></div></td><td><div><div><p>Authorization endpoint URL of the OAuth 2.0 service. For example: <code>https://dev-12345.okta.com/oauth2/v1/authorize</code>.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Token Endpoint</p></div></div></td><td><div><div><p>Token endpoint of the OAuth 2.0 service. For example: <code>https://dev-12345.okta.com/oauth2/v1/token</code>.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Scopes</p></div></div></td><td><div><div><p>Space or comma separated list of the OAuth 2.0 scopes required for in-task authentication. For example: <code>openid profile email transaction:execute</code>.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Redirect URI</p></div></div></td><td><div><div><p>OAuth 2.0 redirect URI that the client uses in the authorization flow.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Token Audience</p></div></div></td><td><div><div><p>OAuth 2.0 token audience. The intended recipient of the token. For example: <code>https://my-agent.example.com/api</code>.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Response Type</p></div></div></td><td><div><div><p>OAuth 2.0 response type. Typically <code>code</code> for authorization code flow.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Code Challenge Method</p></div></div></td><td><div><div><p>PKCE code challenge method. Typically <code>S256</code> for SHA-256.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Body Encoding</p></div></div></td><td><div><div><p>Encoding format for token request body. Typically <code>form</code> for <code>application/x-www-form-urlencoded</code>. Default: <code>form</code>.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Token Timeout</p></div></div></td><td><div><div><p>Timeout in seconds for token requests.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Challenge Response Status Code</p></div></div></td><td><div><div><p>HTTP status code to return for <code>auth-required</code> challenge responses. Typically <code>200</code> to maintain JSON-RPC compatibility.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When enabled, the token cache is shared across Omni Gateway replicas. Enable this option when running more than one replica to avoid duplicate token requests or repeated auth challenges.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr></tbody></table>

## Token Handling

For `GET` and `POST` requests, the policy handles the token differently:

- **GET**: The policy removes the request body after the token extraction.

- **POST**: The policy removes only the token property from the body and preserves the rest of the
  body.

The token is always removed from the body after extraction to prevent token leakage to the upstream
service. The extracted token is set in the `Authorization` header as the `Bearer <token>` before
forwarding the request. This overrides any existing `Authorization` header. Perform any
authentication of the first authorization header prior to this policy.

The policy extracts the token from `$.params.message.parts[].data.auth_credentials.accessToken`. For
example, using the default JSONPath, the policy extracts the token
(`"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…​"`) from the following request body:

```json
{
  "jsonrpc": "2.0",
  "id": "req-18",
  "method": "message/send",
  "params": {
    "taskId": "task-123",
    "contextId": "ctx-456",
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "data",
          "data": {
            "auth_credentials": {
              "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
            }
          }
        }
      ]
    }
  }
}
```

## Challenge Response Format

If no secondary authentication token is found, the policy returns an `auth-required` A2A task
response. The response preserves the `taskId` and `contextId` from the request if originally
provided:

```json
{
  "jsonrpc": "2.0",
  "id": "req-18",
  "result": {
    "id": "task-123",
    "contextId": "ctx-456",
    "status": {
      "state": "auth-required",
      "message": {
        "kind": "message",
        "role": "agent",
        "messageId": "msg-abc123",
        "taskId": "task-123",
        "parts": [
          {
            "kind": "text",
            "text": "To continue this task, additional authorization is required."
          },
          {
            "kind": "data",
            "data": {
              "authChallenge": {
                "secondaryAuthProvider": "okta",
                "authorizationEndpoint": "https://dev-12345.okta.com/oauth2/v1/authorize",
                "tokenEndpoint": "https://dev-12345.okta.com/oauth2/v1/token",
                "scopes": ["openid", "profile", "email"],
                "audience": "https://my-agent.example.com/api",
                "redirectUri": "https://myapp.example.com/oauth/callback",
                "responseType": "code",
                "codeChallengeMethod": "S256",
                "bodyEncoding": "form"
              }
            }
          }
        ],
        "metadata": {}
      },
      "timestamp": "2025-01-01T00:00:00.000Z"
    },
    "kind": "task"
  }
}
```

## Token caching

When the request body includes a secondary access token, the policy stores it for later reuse. When
the body doesn’t include a token, the policy tries the cache before returning an `auth-required`
challenge:

- The cache is keyed per user and is derived from the bearer JWT in the inbound `Authorization`
  header. The policy uses the first available of the `sub`, `email`, `azp`, or OAuth client
  identifier claims. If that JWT can’t be parsed or none of these claims is present, the policy does
  not cache or reuse tokens.

- Cache entry lifetime is derived from the token timeout. When a token expires, it’s discarded from
  the cache.

## See Also

- [Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-outbound-directory)

- [Credential Injection OAuth 2.0](https://docs.mulesoft.com/gateway/1.13/policies-outbound-oauth)

- [A2A Agent Card Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-agent-card)

- [A2A Schema Validation Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-schema-validation)