title: Task Authorization

description: Per-user access control for A2A tasks — ownership, read/write checks, and user identity across transports.

layout: page

Implement `TaskAuthorizationProvider` to control per-user access:

public class MyTaskAuthorizationProvider implements TaskAuthorizationProvider {

@Override

public boolean checkRead(ServerCallContext context, String taskId, TaskOperation op) {

return isOwner(context.getUser(), taskId);

}

@Override

public boolean checkWrite(ServerCallContext context, String taskId, TaskOperation op) {

return isOwner(context.getUser(), taskId);

}

@Override

public boolean checkCreate(ServerCallContext context, TaskOperation op) {

return context.getUser() != null && context.getUser().isAuthenticated();

}

@Override

public boolean isTaskRecorded(String taskId) {

return ownershipStore.contains(taskId);

}

@Override

public void recordOwnership(ServerCallContext context, String taskId, TaskOperation op) {

if (context.getUser() != null) {

ownershipStore.put(taskId, context.getUser().getUsername());

}

}

}

The SDK discovers the bean via CDI automatically — no additional wiring needed.

Authorization decisions rely on `context.getUser()` returning the authenticated user. How the user is populated depends on the transport:

- **JSON-RPC and REST**: The Quarkus route handler extracts the user from the Vert.x routing context (`rc.userContext()`) and sets it on `ServerCallContext` directly.

- **gRPC**: The reference server includes a `QuarkusCallContextFactory` CDI bean that injects the Quarkus `SecurityIdentity` and maps it to the `ServerCallContext` `User`. This happens automatically when using the reference gRPC module. If you provide your own `CallContextFactory`, you are responsible for populating the user.

| Operation | Authorization check |

|-----------|---------------------|

| `getTask`, `subscribeToTask`, `getTaskPushNotificationConfig`, `listTaskPushNotificationConfigs` | `checkRead` |

| `cancelTask`, `createTaskPushNotificationConfig`, `deleteTaskPushNotificationConfig` | `checkWrite` |

| `messageSend` / `messageSendStream` (existing task) | `checkWrite` |

| `messageSend` / `messageSendStream` (new task) | `checkCreate`, then `recordOwnership` |

| `listTasks` | `checkRead` per task |

title: Bill of Materials (BOM)

description: Dependency management BOMs for the A2A Java SDK — SDK, Extras, and Reference BOMs.

layout: page

The A2A Java SDK provides three BOMs for different use cases, so you can manage dependency versions in one place.

**Artifact:** `org.a2aproject.sdk:a2a-java-sdk-bom`

Includes all A2A SDK core modules (spec, server, client, transport), core third-party dependencies, Jakarta APIs, and test utilities.

**Use this BOM when:** Building A2A agents with any framework (Quarkus, Spring Boot, vanilla Java, etc.)

**Artifact:** `org.a2aproject.sdk:a2a-java-sdk-extras-bom`

Includes everything from the SDK BOM plus server-side enhancement modules (database persistence, distributed queue management, etc.).

**Use this BOM when:** Building production A2A servers needing advanced server-side features beyond the core SDK.

**Artifact:** `org.a2aproject.sdk:a2a-java-sdk-reference-bom`

Includes everything from the SDK BOM plus the Quarkus BOM (complete Quarkus platform), A2A reference implementation modules, and the TCK module for testing.

**Use this BOM when:** Building Quarkus-based A2A agents or reference implementations.

<dependencyManagement>

<dependencies>

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-bom</artifactId>

<version>$\{org.a2aproject.sdk.version}</version>

<type>pom</type>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<dependencies>

<!-- No version needed - managed by BOM -->

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-server-common</artifactId>

</dependency>

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-transport-jsonrpc</artifactId>

</dependency>

</dependencies>

<dependencyManagement>

<dependencies>

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-extras-bom</artifactId>

<version>$\{org.a2aproject.sdk.version}</version>

<type>pom</type>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<dependencies>

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-server-common</artifactId>

</dependency>

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-extras-task-store-database-jpa</artifactId>

</dependency>

</dependencies>

<dependencyManagement>

<dependencies>

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-reference-bom</artifactId>

<version>$\{org.a2aproject.sdk.version}</version>

<type>pom</type>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<dependencies>

<!-- A2A SDK and Quarkus versions both managed -->

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-reference-jsonrpc</artifactId>

</dependency>

<dependency>

<groupId>io.quarkus</groupId>

<artifactId>quarkus-arc</artifactId>

</dependency>

</dependencies>

See [Backward Compatibility](compatibility#client-communicating-with-v03-agents) for using `Client_v0_3` with older protocol agents.

See [Examples](examples) for Hello World walkthroughs and sample applications.

title: Backward Compatibility

description: Serve v1.0 and v0.3 A2A protocol versions simultaneously — multi-version modules, version routing, and v0.3 client support.

layout: page

Add compat modules alongside v1.0 modules to serve both protocol versions simultaneously. No changes to your `AgentExecutor` are needed.

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-reference-multiversion-jsonrpc</artifactId>

<version>$\{org.a2aproject.sdk.version}</version>

</dependency>

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-reference-multiversion-rest</artifactId>

<version>$\{org.a2aproject.sdk.version}</version>

</dependency>

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-compat-0.3-reference-jsonrpc</artifactId>

<version>$\{org.a2aproject.sdk.version}</version>

</dependency>

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-compat-0.3-reference-rest</artifactId>

<version>$\{org.a2aproject.sdk.version}</version>

</dependency>

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-compat-0.3-reference-grpc</artifactId>

<version>$\{org.a2aproject.sdk.version}</version>

</dependency>

- **JSON-RPC and REST**: When serving multiple protocol versions, version routing inspects the `A2A-Version` HTTP header on each request. If the header is `"1.0"`, the request is routed to the v1.0 handler. If it is `"0.3"` or absent, the request is routed to the v0.3 handler.

- **gRPC**: Version dispatch is implicit — v0.3 clients use the `a2a.v1` protobuf package and v1.0 clients use `lf.a2a.v1`, so requests are routed to the correct service automatically.

- **Agent card**: When both v1.0 and v0.3 are enabled, the v1.0 `AgentCard` takes precedence and is served at `/.well-known/agent-card.json`. The v0.3 `AgentCard_v0_3` is ignored. If only v0.3 is enabled, the v0.3 agent card is used. If only v1.0 is enabled, the v1.0 agent card is used as-is.

When serving both protocol versions, you need to ensure the v1.0 agent card contains fields that v0.3 clients expect. Existing v0.3 client implementations (in any language) look for `url`, `preferredTransport`, and `additionalInterfaces` with `transport`/`url` entries — fields that don't exist in the v1.0 format by default.

To make your v1.0 `AgentCard` parsable by v0.3 clients, set these fields on the builder:

AgentCard card = AgentCard.builder()

.name("My Agent")

// ... other v1.0 fields ...

.supportedInterfaces(List.of(

new AgentInterface("jsonrpc", "http://localhost:9999")))

// v0.3 backward-compatibility fields:

.url("http://localhost:9999")

.preferredTransport("jsonrpc")

.additionalInterfaces(List.of(

new Legacy_0_3_AgentInterface("jsonrpc", "http://localhost:9999")))

.build();

The two interface lists serve different clients:

- `supportedInterfaces` — used by **v1.0 clients** to discover endpoints (uses `AgentInterface` with `protocolBinding`/`url`/`tenant` fields)

- `additionalInterfaces` — used by **v0.3 clients** to discover endpoints (uses `Legacy_0_3_AgentInterface` with v0.3 field names: `transport`/`url`)

- `url` and `preferredTransport` — top-level fields that v0.3 clients use to discover the primary endpoint

Push notification payloads are automatically formatted to match the protocol version used when the push notification configuration was registered. When a v0.3 client registers a push notification configuration (via any transport), the server records the protocol version alongside the configuration. When a notification is later sent to that webhook, the payload is formatted as a v0.3 Task object. Configurations registered by v1.0 clients receive v1.0 `StreamResponse` payloads as usual. This happens transparently — no additional configuration is needed beyond adding the compat reference module.

Use `Client_v0_3` to communicate with agents that only support protocol v0.3:

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-compat-0.3-client</artifactId>

<version>$\{org.a2aproject.sdk.version}</version>

</dependency>

<dependency>

<groupId>org.a2aproject.sdk</groupId>

<artifactId>a2a-java-sdk-compat-0.3-client-transport-jsonrpc</artifactId>

<version>$\{org.a2aproject.sdk.version}</version>

</dependency>

gRPC and REST transports are also available:

- `a2a-java-sdk-compat-0.3-client-transport-grpc`

- `a2a-java-sdk-compat-0.3-client-transport-rest`

AgentCard card = A2ACardResolver.builder().baseUrl("http://localhost:1234")

.build().getAgentCard();

AgentInterface v03Interface = card.supportedInterfaces().stream()

.filter(i -> A2AProtocol_v0_3.PROTOCOL_VERSION.equals(i.protocolVersion()))

.findFirst().orElseThrow();

Client_v0_3 client = ClientBuilder_v0_3.forUrl(v03Interface.url())

.withTransport(JSONRPCTransport_v0_3.class, new JSONRPCTransportConfigBuilder_v0_3())

.build();

**Note:** `Client_v0_3` exposes only operations available in protocol v0.3. For example, `listTasks()` is not available (it was added in v1.0). Return types use v0.3 domain objects from the `org.a2aproject.sdk.compat03.spec` package.