Authentication

The Claude API supports three ways to authenticate requests:

API keys and Workload Identity Federation grant the same access to Claude API endpoints. Choose API keys to get started quickly: a personal key for your own development, or a service account key for anything shared. Move to Workload Identity Federation when your workload already has a platform-issued identity you can federate. Use App Attest for iOS and macOS apps you distribute to end users.

API keys

API keys are static secrets that you generate in the Claude Console and send on every request in the x-api-key header.

Key types

When you create a key, you choose its type, which determines what the key can do, where it works, and when it stops working:

Personal keys and service account keys are identity-backed: each belongs to a user or service account your organization already manages, and every request acts as that identity. When that identity is removed from the organization, the key stops working. This means that keys won't accidentally outlive the people or workloads that own them. Prefer them over workspace keys for new integrations.

Use a personal key for your own development and scripts. A shared personal key acts as one person and breaks when they leave. For shared or automated workloads (CI, production services), have an organization admin create a service account so the workload has its own identity.

Workspace API keys still work but should be considered legacy; identity-backed keys or Workload Identity Federation are preferred. To migrate, see Replacing workspace API keys.

Create and use a key

• Create a key: Go to Settings → API keys in the Claude Console and click Create key. Name the key and choose an expiration. Set Linked account to yourself for a personal key, or to a service account for a key shared across multiple users. You can also scope the key to a specific workspace, which lets you skip setting a workspace ID manually in future requests.
• Use the key: Set the x-api-key header on direct HTTP requests, or set the ANTHROPIC_API_KEY environment variable and the client SDKs pick it up automatically.

POST /v1/messages
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

Store API keys in a secrets manager, rotate them periodically, and disable or delete any key you suspect has leaked. On the API keys page, Disable is reversible (the Admin API reports the key's status as "inactive", and Re-enable returns it to "active"), while Delete is permanent: the key is archived and still appears in List API Keys with status: "archived". Expired keys can only be deleted. You can also set an expiration when you create a key to limit how long a leaked credential stays usable.

client = Anthropic(api_key="my-anthropic-api-key")
# or, with ANTHROPIC_API_KEY set in the environment:
client = Anthropic()

Select a workspace

API keys that are created for a specific workspace only work in that workspace, and API requests using these keys can omit the workspace ID.

If your API key isn't scoped to a workspace, you must specify the workspace ID in the anthropic-workspace-id header for each request. See the following example for how to set this header in a request or in SDKs.

The Admin API accepts a personal key or service account key only if the key isn't scoped to a specific workspace.

You can find a workspace's ID in the ID column of Settings → Workspaces in the Claude Console, or by calling the List Workspaces endpoint. Neither lists the Default Workspace's ID: read it from the anthropic-workspace-id response header of any request that runs there (for example, one made with a workspace key from the Default Workspace), or from scope.workspace_id on such a key in List API Keys.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# Required on every request for a multi-workspace key.
# Omit extra_headers for a single-workspace key.
message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    extra_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)
print(message.content)

# Or set it once for every request from this client:
workspace_client = Anthropic(
    default_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)

If a request made with a key that isn't scoped to a workspace omits the header, the API returns a 400 invalid_request_error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "anthropic-workspace-id is required when authenticating with an identity-linked API key; send the id of the workspace this request acts in."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

A header value that isn't a valid workspace ID returns a 400 invalid_request_error with the message anthropic-workspace-id header must be a valid workspace ID. If the workspace doesn't exist, or the key's user or service account doesn't have access to it, the API returns a 404 not_found_error with the message Workspace `<id>` not found., the same response as for any unknown workspace.

Workload Identity Federation selects a workspace at token exchange instead; see the WIF reference for details.

Key expiration

When you create an API key from the API keys page in the Claude Console, you choose an expiration: a preset (3 hours, 1 day, 7 days, or 30 days), a custom duration, or Never for keys you store in a secrets manager and rotate yourself. If your organization has a maximum expiration policy, the Console limits presets and custom durations to the policy maximum, and Never is unavailable. Existing keys keep their current behavior; expiration is set at creation time and cannot be changed afterward. The same expiration choice applies when you create an Admin API key in the Claude Console.

Anthropic emails the key's creator as the expiration approaches: 7 days before expiration for keys created with a lifetime of at least 14 days, and 1 day before for keys with a lifetime of at least 7 days. Keys with shorter lifetimes expire without a warning email.

After a key expires, requests made with it return a 401 authentication_error. Create a new key to restore access; expired keys cannot be reactivated.

The Console API keys table shows each key's expiration, and the Admin API reports each key's expires_at timestamp on the List API Keys and Retrieve API Key endpoints, so you can audit and rotate keys before they expire. The field is null for keys without an expiration.

Expiration limits the lifetime of a leaked credential, but it is not a substitute for secret hygiene. Regardless of expiration, store keys in a secrets manager and disable or delete any key you suspect has leaked.

Replacing workspace API keys

If you have a workspace key, you may want to replace it with Workload Identity Federation or a personal or service account key. This provides better security and observability.

See Workload Identity Federation for details on configuring Workload Identity Federation, which is preferred over long-lived keys.

To replace a workspace key with a personal or service account key:

1. Decide the key type. Your own tooling should use a personal key. A shared or unattended workload should use a service account key.
2. Create a service account if necessary. You may have to ask an organization admin to create one in Settings → Service accounts and add it to the relevant workspace.
3. Create the new key. Create it specifically for the integration's workspace unless multiple workspaces are needed.
4. Deploy the new key. Replace the old key wherever the integration reads it, typically the ANTHROPIC_API_KEY environment variable or a secrets manager entry. For a multi-workspace key, also send the anthropic-workspace-id header as shown in Select a workspace.
5. Delete the old key. Confirm that requests succeed, then delete the workspace key on the API keys page.

Workload Identity Federation

Workload Identity Federation (WIF) lets a workload authenticate with a short-lived identity token issued by an identity provider (IdP) you already trust, such as AWS IAM, Google Cloud, or any standards-compliant OIDC issuer (such as GitHub Actions, Kubernetes service accounts, SPIFFE, Microsoft Entra ID, or Okta). The workload exchanges its IdP-issued JWT at POST /v1/oauth/token for a short-lived Claude API access token, and the SDK refreshes that token automatically before it expires. There is no sk-ant-api... string to mint, distribute, or rotate.

Federation removes long-lived Claude API keys from your environment, which shrinks the blast radius of a leaked credential and lets you manage access with the same IdP controls you already use for cloud resources. It does not, on its own, guarantee end-to-end security: the trust chain is only as strong as your identity provider's configuration, and a long-lived secret one hop upstream (for example, a static cloud credential that can mint IdP tokens) can still undermine it. Pair federation with your provider's controls, such as IP allowlists, MFA, and audit logging.

To configure federation, you create three resources in the Claude Console (a service account, a federation issuer, and a federation rule) and then point your SDK at the rule. See Workload Identity Federation for the full setup walkthrough.

App Attest

App Attest authenticates iOS and macOS apps that call the Claude API directly from the device. Each installation proves that it is a genuine, unmodified build of an app you registered in the Claude Console, using Apple's App Attest service. Anthropic then issues the device a short-lived access token that bills usage to your workspace. Tokens are scoped to your workspace, expire after one hour, and authorize only Messages API calls.

To register your app and get a client ID, see App Attest for iOS and macOS apps.

Next steps