anthropic-managed changedbuild-with-claude/claude-models-on-google-cloud/anthropic-managed

A whole new page. There's nothing to diff it against, so here is what it says.

---
title: Claude Models on Google Cloud (Anthropic managed)
url: https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed
description: Claude Models on Google Cloud (Anthropic managed) is the Claude API, run by Anthropic and reached through your Google Cloud project.
---

Google Cloud handles access and billing for Claude Models on Google Cloud (Anthropic managed). To compare the two Google Cloud offerings, or to check which one you use, see [Claude Models on Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/overview).

## Set up your account

To set up your account for Claude Models on Google Cloud (Anthropic managed), you need the following:

* Permission to purchase in Google Cloud Marketplace on your billing account
* Permission to enable services on the project
* An [IAM role that lets you open the Claude Console](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console), which you need for step 4

These steps create a new Anthropic organization for your Google Cloud project. It's separate from any Anthropic organization your company already has. That includes a Claude Enterprise organization. To move from an existing organization, see [Moving from an existing Anthropic organization](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#moving-from-an-existing-anthropic-organization).

If you have an existing discount, contact your Anthropic or Google Cloud account representative before you start these steps. Discounts can't be applied to past usage.

<Steps>
  <Step title="Subscribe in Marketplace">
    1. Open [Google Cloud Marketplace](https://console.cloud.google.com/marketplace) and find the **Claude Models on Google Cloud (Anthropic managed)** listing.
    2. Click **Subscribe** and complete the purchase flow.
    3. Return to the listing and click **Manage on Console**. This opens the Claude page in the Google Cloud console.

    To return to the Claude page later, select your project in the Google Cloud console. Then go to **Agent Platform > Models > Claude Platform** and select **Anthropic managed**.
  </Step>

  <Step title="Enable the services">
    Enable two services on every project that calls Claude Models on Google Cloud (Anthropic managed):

    * `claude.googleapis.com` serves the API for Claude Models on Google Cloud (Anthropic managed). This service also defines the IAM permissions. Calls fail without it.
    * `anthropic-managed-claude.cloudpartnerservices.goog` is the Marketplace service that attributes the project's usage to your subscription.

    ```bash CLI
    gcloud services enable claude.googleapis.com \
      anthropic-managed-claude.cloudpartnerservices.goog \
      --project=my-project-id
    ```

    Replace `my-project-id` with your project ID.

    You can also enable both from the Claude page or from **APIs & Services**. Enabling is a one-time step for each project. To check that both services are enabled, run `gcloud services list --enabled --project=my-project-id` and look for both names.
  </Step>

  <Step title="Set up your Anthropic organization">
    1. On the Claude page, click **Activate**.
    2. In the Anthropic setup flow, enter a contact email address.
    3. Open the setup link sent to that address.
    4. Fill in the organization's name, entity type, country, and intended use.
    5. Accept Anthropic's Commercial Terms of Service and Usage Policy.

    The contact address is used only for setup and service notices. For how people open the Claude Console after setup, see [Using the Claude Console](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console).
  </Step>

  <Step title="Open the Claude Console">
    When your Anthropic organization is active, the button on the Claude page changes to **Open Claude Console**. Click it. Google Cloud checks your IAM access. Then it redirects your browser to `platform.claude.com`. You're signed in to the new organization.

    While you're in the Claude Console, [find your workspace ID](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#find-your-workspace-id) and copy it. Everyone who calls Claude Models on Google Cloud (Anthropic managed) needs it. Pass it on to your developers.
  </Step>
</Steps>

To add another project, repeat these steps in that project, starting from step 2.

### Troubleshooting account setup

If you run into one of the following problems while you set up Claude Models on Google Cloud (Anthropic managed), apply its fix:

* **`gcloud services enable` can't find `anthropic-managed-claude.cloudpartnerservices.goog`:** Run the command as the account that completed the Marketplace purchase, or contact your Anthropic account representative.
* **A permission error on your first API call:** Check that `claude.googleapis.com` is enabled on the project you're calling. Check that the caller has `roles/claude.user` or `roles/claude.admin` on that project. For what each role allows, see [IAM roles](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles). A new grant or a newly enabled service can take a moment to apply.
* **"Signed in as a different account" after following the setup link:** Click **Log out and continue**. Then use the email address you entered in step 3.
* **The button says "Finish Setup" instead of "Open Claude Console":** Your Anthropic organization exists, but its setup isn't complete. An administrator has to finish the organization details form.
* **The Usage page shows no data after your first API call:** Usage data can take a few minutes to appear in the Claude Console.

## Manage access

### IAM roles

Claude Models on Google Cloud (Anthropic managed) has three predefined IAM roles. Grant roles on the project.

| Role                  | Display name  | What it allows                                                                                                                                                                                                                          |
| --------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roles/claude.viewer` | Claude Viewer | Every `get` and `list` permission on workspace resources<br />This role is read-only.                                                                                                                                                   |
| `roles/claude.user`   | Claude User   | Everything `roles/claude.viewer` allows, plus creating and changing workspace resources<br />This includes sending messages and counting tokens. It also includes managing batches, files, skills, and Claude Managed Agents resources. |
| `roles/claude.admin`  | Claude Admin  | Everything `roles/claude.user` allows, plus the permissions checked on your Anthropic organization<br />Organization-level routes act on your Anthropic organization as a whole, not on one workspace.                                  |

For example, the following command lets a service account call Claude Models on Google Cloud (Anthropic managed):

```bash CLI
gcloud projects add-iam-policy-binding my-project-id \
  --member="serviceAccount:[email protected]" \
  --role="roles/claude.user"
```

For permissions, predefined roles, and audit log types, see [IAM permissions for Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/api/claude-models-on-google-cloud-anthropic-managed-iam-permissions).

Enabling `claude.googleapis.com` creates a service agent for the project. Don't remove its role grants. Removing them stops Claude Models on Google Cloud (Anthropic managed) from working in the project.

### Using the Claude Console

With Claude Models on Google Cloud (Anthropic managed), you can't use an email address to sign in to your Anthropic organization. Instead, click **Open Claude Console** on the [Claude page](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#set-up-your-account) in the Google Cloud console. Google Cloud IAM controls who can open the Claude Console. Of the three predefined [IAM roles](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles), only `roles/claude.admin` on the project lets you open the Claude Console.

### Workspaces

In Claude Models on Google Cloud (Anthropic managed), setup creates your Anthropic organization with one workspace, the Default Workspace. To create more workspaces, [open the Claude Console](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console) and go to **Settings > Workspaces**. On the same page, you can rename or archive any workspace except the Default Workspace. Each workspace has its own [workspace ID](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#find-your-workspace-id). Files, skills, batches, Claude Managed Agents sessions, and other workspace resources belong to the workspace whose ID you [set for the request](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution).

You grant [IAM roles](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles) on the project, so a role applies to every workspace in that project. When teams need separate access, give each team its own Google Cloud project. Each project has its own Anthropic organization, so repeat the [setup steps](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#set-up-your-account) in each project, starting from step 2.

## Before making API calls

To call Claude Models on Google Cloud (Anthropic managed), you need the following:

1. A Google Cloud project with an active subscription and an Anthropic organization whose setup is complete. See [Set up your account](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#set-up-your-account).
2. The [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed, for local development.
3. The `roles/claude.user` role, granted on the project to the identity that makes the calls.
4. Application Default Credentials for that identity. See [Authentication](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#authentication).
5. Your project ID and your [workspace ID](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#find-your-workspace-id).

To grant the role to your own account for local development, run the following command. You need permission to change the project's IAM policy.

```bash CLI
gcloud projects add-iam-policy-binding my-project-id \
  --member="user:[email protected]" \
  --role="roles/claude.user"
```

Replace `my-project-id` with your project ID. Replace `[email protected]` with your Google account's email address. To see the project gcloud is using, run `gcloud config get-value project`. For service accounts and the other roles, see [IAM roles](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles).

### Find your workspace ID

To find your workspace ID for Claude Models on Google Cloud (Anthropic managed), [open the Claude Console](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console) and go to **Settings > Workspaces**. The ID starts with `wrkspc_`. If you can't open the Claude Console, ask someone who can open it to send you the ID.

Set the project and workspace as environment variables so that the SDK client and the [`ant` CLI](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/quickstart) pick them up:

```bash CLI
export ANTHROPIC_GOOGLE_CLOUD_PROJECT="my-project-id"
export ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID="wrkspc_01AbCdEf23GhIj"
```

### Install an SDK

The [SDK client](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) for Claude Models on Google Cloud (Anthropic managed) is `AnthropicGoogleCloud` (csharp: `AnthropicGoogleCloudClient`; go: `googlecloud.NewClient`; java: `GoogleCloudBackend`; php: `Anthropic\GoogleCloud\Client`; ruby: `Anthropic::GoogleCloudClient`). The client resolves your Google credentials. It also builds the base URL from your project, location, and workspace ID.

<Note>
  The SDK client for Claude Models on Google Cloud (Anthropic managed) is in beta.
</Note>

Install the package that provides the client:

<Tabs>
  <Tab title="Python">
    ```bash
    pip install -U "anthropic[google_cloud]"
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash
    npm install @anthropic-ai/google-cloud-sdk
    ```
  </Tab>

  <Tab title="C#">
    ```bash
    dotnet add package Anthropic.GoogleCloud
    ```
  </Tab>

  <Tab title="Go">
    ```bash
    go get github.com/anthropics/anthropic-sdk-go/v2
    ```
  </Tab>

  <Tab title="Java">
    ```kotlin Gradle
    implementation("com.anthropic:anthropic-java:3.1.0")
    implementation("com.anthropic:anthropic-java-google-cloud:3.1.0")
    ```

    ```xml Maven
    <dependency>
      <groupId>com.anthropic</groupId>
      <artifactId>anthropic-java</artifactId>
      <version>3.1.0</version>
    </dependency>
    <dependency>
      <groupId>com.anthropic</groupId>
      <artifactId>anthropic-java-google-cloud</artifactId>
      <version>3.1.0</version>
    </dependency>
    ```
  </Tab>

  <Tab title="PHP">
    ```bash
    composer require anthropic-ai/sdk google/auth
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash
    gem install anthropic googleauth
    ```
  </Tab>
</Tabs>

To use the `ant` CLI instead, [install or update the CLI](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/quickstart#installation) to the latest version. A version without support for Claude Models on Google Cloud (Anthropic managed) ignores the `ANTHROPIC_GOOGLE_CLOUD_*` variables. It then does one of the following:

* Sends the request to the Claude API with any other credential you've set up
* Fails with an authentication error

## Making requests

Claude Models on Google Cloud (Anthropic managed) serves Claude API endpoints under a base URL that names your project, a location, and your workspace:

```text wrap
https://claude.googleapis.com/v1/projects/{project}/locations/global/workspaces/{workspace}/invoke
```

The [organization-level routes](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles), whose paths start with `/v1/organizations/`, use a base URL without the workspace:

```text wrap
https://claude.googleapis.com/v1/projects/{project}/locations/global/claudeOrganization/invoke
```

If you don't [set the base URL](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution), the SDK client chooses between these two for each request.

Append the Claude API path to the base URL. For example, the [Messages API](https://platform.claude.com/docs/en/api/messages/create) is at `.../invoke/v1/messages`. Three things differ from a Claude API request:

* **Base URL:** The project-scoped URLs shown earlier, in place of `https://api.anthropic.com`.
* **Authentication:** An `Authorization: Bearer` header with a Google access token. Don't send an `x-api-key` header.
* **Workspace:** The workspace ID is part of the URL. Don't send an `anthropic-workspace-id` header.

Everything else is the same as on the Claude API, including the following:

* The `anthropic-version` and `anthropic-beta` headers
* The request body
* Streaming
* The response

Code samples elsewhere in this documentation create the Claude API client and read an API key. To run one with Claude Models on Google Cloud (Anthropic managed), replace its import and client constructor with the ones in the following examples. For a cURL sample, apply the three differences listed earlier.

Before running these examples, complete the steps in [Before making API calls](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#before-making-api-calls).

<CodeGroup>
  ```bash cURL
  curl "https://claude.googleapis.com/v1/projects/$ANTHROPIC_GOOGLE_CLOUD_PROJECT/locations/global/workspaces/$ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID/invoke/v1/messages" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "content-type: application/json" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "messages": [
        {"role": "user", "content": "Hello, Claude"}
      ]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-opus-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Claude"}'
  ```

  ```python Python
  from anthropic import AnthropicGoogleCloud

  client = AnthropicGoogleCloud()

  message = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      messages=[{"role": "user", "content": "Hello, Claude"}],
  )
  print(message)
  ```

  ```typescript TypeScript
  import { AnthropicGoogleCloud } from "@anthropic-ai/google-cloud-sdk";

  const client = new AnthropicGoogleCloud();

  const message = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }]
  });
  console.log(message);
  ```

  ```csharp C#
  using Anthropic.GoogleCloud;
  using Anthropic.Models.Messages;

  var client = new AnthropicGoogleCloudClient();

Cut at 300 lines. The page has the rest.

No line in this hunk matches that.