What you will be able to do
- Choose between personal, service account, legacy workspace and Admin API keys based on whose identity each carries and when it stops working
- Tell an authentication failure (401) from an insufficient-level failure (403) and fix each one
- Predict how the API responds when a key's workspace scope and the request's workspace don't match
- Store, expire and rotate keys from a laptop .env file through to a production secrets manager
- Respond to a suspected leak and limit its damage with scanning, deactivation, spend limits and usage monitoring
Key concept
Identity-backed API key — A personal or service account key acts as a user or service account your organization already manages, so its access follows that identity. When the identity is removed, the key stops working and can't outlive its owner.
1.Key types and whose identity a key carries
Every Claude API request acts as someone, and the type of key decides who. A static API key is an sk-ant-api... secret sent as Authorization: Bearer <key> on each request. When you create one in the Claude Console under Settings → API keys, the Linked account field sets its type. Link it to yourself for a personal key, or to a service account for a key that several people or a workload share. The type decides what the key can reach and when it stops working.
| Key type | Acts as | Stops working when |
|---|---|---|
| Personal key | You, with your roles and permissions | You lose access to the organization (or to the workspace, for a single-workspace key); archived keys are not restored if you are re-invited |
| Service account key | A service account | The service account is archived or, for a single-workspace key, removed from that workspace |
| Workspace key (legacy) | No one: it belongs to the workspace | It expires, is disabled or deleted, or its workspace is archived, whatever happens to its creator |
Personal and service account keys are identity-backed. Every request runs with the permissions of a user or service account the organization already manages, so removing that identity cuts off the key too. The legacy workspace key is the exception. It has no owner, so it keeps working after the engineer who created it leaves. That is why a departed colleague's workspace key can still drive a pipeline months later, and it is why new integrations should prefer identity-backed keys.
Choosing between the two identity-backed types depends on who runs the code. Your own scripts and development use a personal key. A personal key shared with a team acts as one person and breaks when that person leaves. CI jobs and production services need their own service account, which an organization admin creates so the workload has its own identity.
Admin API keys are a separate kind of credential, used to manage the organization rather than call models. In the Claude Console only organization members with the admin role can create one, under Settings → Admin keys, and it carries the prefix sk-ant-admin01-.... One Admin API key authenticates the Admin API, the Usage and Cost API, the Rate Limits API and the other Admin-section APIs. A key created in one organization cannot manage a different one.
Authentication is the API establishing who is calling, and the key is the proof. A key travels as a bearer token in the Authorization header; the older x-api-key header is still accepted in its place, and Admin API calls are normally sent that way. A key that is unknown, archived or expired fails at this step with 401 authentication_error. An expired key never comes back, so the fix is a new key. Federated workload identity is the other route to a Claude token, covered in the federation pages of this lesson.
Level verification is the separate check that an authenticated caller is allowed to do this particular thing, and its failure looks different: 403 Forbidden. For a personal key, the level is the owner's organization role. A developer can manage API keys, while managing users takes admin. Claude Enterprise keys carry explicit scopes such as read:members or read:analytics, fixed when the key is created. A call outside them returns a 403 naming the scopes the key has and the scopes the endpoint needs. Widening a key means creating a new one. Console Admin API keys have no selectable scopes and carry full access to every endpoint that accepts them, and the service-account and federation endpoints accept only an org:admin OAuth token, so an Admin API key is refused there however privileged its creator is. Read the status code first: 401 means fix the credential, 403 means fix the level.
Checkpoint 1 of 8· Check yourself
An engineer leaves the company and is removed from the organization. Which of their keys still authenticate requests the next day?
Personal keys are archived when their owner is removed. A workspace key belongs to its workspace, not to a person, so it survives its creator's departure.
“It expires, is disabled or deleted, or its workspace is archived, regardless of whether its creator leaves the organization”Source: platform.claude.com
Checkpoint 2 of 8· Exam question
A team configures their Claude Agent SDK session with `permission_mode: "bypassPermissions"` and `allowed_tools: ["Read"]`, believing this restricts the agent to read-only file access for safety during an autonomous refactor. During the run, the agent successfully executes a `Bash` command that deletes a directory. What is the correct explanation for this outcome?
Correct answer: A — `allowed_tools` only pre-approves the tools listed; unlisted tools like `Bash` are not matched by any allow rule and fall through to the permission mode, where `bypassPermissions` approves them anyway.
- A. Correct. allowed_tools does not constrain bypassPermissions: it only pre-approves listed tools, and any tool not covered by an allow or deny rule still falls through to the permission mode step, where bypass mode approves everything.
- B. Incorrect. This combination is valid syntax and a documented (if dangerous) configuration; the SDK does not reject it.
- C. Incorrect. This is the inverse of the actual behavior: bypassPermissions approves tools regardless of allowed_tools, not only the ones listed in it, so nothing here indicates a bug.
- D. Incorrect. While a PreToolUse hook could have blocked this, hooks are not the only mechanism; using disallowed_tools to remove Bash entirely, or avoiding bypassPermissions, would also have prevented it.
Moving an integration off a workspace key follows a fixed sequence. The old key goes last, so traffic never runs without a working credential.
Checkpoint 3 of 8· Put it in order
Put the steps for replacing a legacy workspace key in order.
- 1.Deploy the new key wherever the integration reads it, such as ANTHROPIC_API_KEY or a secrets manager entry
- 2.Have an organization admin create a service account and add it to the workspace, if needed
- 3.Create the new key for the integration's workspace
- 4.Decide the key type: personal for your own tooling, service account for shared or unattended workloads
- 5.Confirm requests succeed, then delete the old workspace key
The new identity and key must exist and be serving traffic before the old key is deleted. Otherwise the integration loses access in between.
“Confirm that requests succeed, then delete the workspace key on the API keys page.”Source: platform.claude.com
2.How the API verifies which workspace a key can act in
A key's workspace scope decides how much each request has to tell the API. If a key was created for one workspace, it works only there, and its requests can leave out the workspace ID. A key that isn't scoped to a workspace has to name one on every request in the anthropic-workspace-id header. If the header is missing, the API returns 400 invalid_request_error.
Checkpoint 4 of 8· Fill the gap
This request uses a multi-workspace key. Which header name completes it?
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
extra_headers={" ? ": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)A key that isn't scoped to a workspace has to send anthropic-workspace-id on every request. You can also set it once with default_headers on the client.
The header names a workspace, and the key's identity still has to be allowed in it. A malformed ID gets a 400. A well-formed ID for a workspace the key's user or service account can't access gets 404 not_found_error, the same response as for a workspace that doesn't exist. Because both cases look the same, a 404 here usually points to missing membership, not a typo. Service accounts are implicitly members of the Default Workspace, and every other workspace has to be added to them explicitly.
The Admin API checks scope the other way around. It accepts a personal or service account key only when that key is not scoped to a specific workspace. A single-workspace personal key from an admin's laptop will therefore fail against organization-management endpoints, even though the admin's role would allow the action.
Checkpoint 5 of 8· Check yourself
A service account key with access to all workspaces sends a valid-format workspace ID for a workspace the service account was never added to. What comes back?
A valid ID that the key's identity can't reach gets the same 404 as an unknown workspace. A 400 is only for a missing or malformed header.
“the key's user or service account doesn't have access to it, the API returns a 404 not_found_error”Source: platform.claude.com
Sources1
3.Storing, expiring and rotating keys
Leaks most often happen in two ways: a plaintext key committed to a public repository, or a key pasted into a third-party tool. Anything you give a key to can spend from your account. Uploading a key to a web IDE, cloud provider or CI/CD platform gives that tool's developer access to your Claude Console account, so add it only as an encrypted secret and never in code or config files. Each person who needs API access should get their own key rather than borrow yours.
Where you store a key depends on where the code runs. On a laptop, a .env file loaded with python-dotenv is fine, provided the file is listed in .gitignore. In the cloud, use encrypted secret storage instead of dotenv files: the platform's secret manager injects the key as ANTHROPIC_API_KEY, which the SDK reads automatically. As the number of keys grows, a key management system gives you one encrypted store with fine-grained access control, audit trails and easier rotation.
Expiration is set once, when the key is created. The Console offers presets of 3 hours, 1 day, 7 days or 30 days, a custom duration, or Never for keys you keep in a secrets manager and rotate yourself. An organization can set a maximum expiration policy, which caps the choices and removes Never. Once created, a key's expiration can't be changed. Anthropic emails the creator before expiry: 7 days ahead for keys with a lifetime of at least 14 days, and 1 day ahead for keys with a lifetime of at least 7 days. After expiry, requests return 401 authentication_error, and the only fix is a new key.
Rotation means creating the new key before retiring the old one, on a regular schedule such as every 90 days. Expiration limits how long a leaked key stays usable. It is not a substitute for good secret hygiene.
Checkpoint 6 of 8· Check yourself
A team created a key with a 30-day expiration and now wants it to last 90 days. What should they do?
Expiration is fixed at creation. Getting a different lifetime means creating a new key and rotating to it.
“expiration is set at creation time and cannot be changed afterward”Source: platform.claude.com
4.Detecting a leak, shutting it down and watching usage
Secret scanning catches keys before or soon after they leak. You can turn on scanning in your source control provider, run a SAST tool such as Gitleaks over your repositories, and add scanning to CI/CD so a secret is caught before it reaches the main branch. Public GitHub has an extra safety net. Through GitHub's Secret scanning partner program, a Claude API key found in a public repository is reported to Anthropic, which deactivates it automatically and emails the affected user.
If you suspect a key is compromised, revoke it immediately, then create a replacement and store it in a secrets manager. The Console offers two actions, and they differ in whether you can undo them. Disable can be undone: the key reports inactive, and Re-enable makes it active again. That suits a key you aren't yet sure about. Delete is permanent: the key is archived and still shows in List API Keys with status: "archived". An expired key can only be deleted.
Checkpoint 7 of 8· Match them up
Match each key state or action to its consequence.
Tap a term, then the definition that fits it.
Only Disable can be undone. Deleted and expired keys can't be brought back, and a key exposed on public GitHub is deactivated without any action from you.
“Disable is reversible (the Admin API reports the key's status as "inactive", and Re-enable returns it to "active")”Source: platform.claude.com
Spend controls limit what a leaked key can cost before anyone notices. The broader limits model is covered in [Rate limits, spend limits and service tiers](lesson:2.1). For a leaked key, the relevant settings are these: Custom Rate Limit organizations should set usage and spend limits, and Standard Rate Limit organizations should set the auto-reload threshold with care, because every reload is more credit an attacker can use.
Monitoring is how you tell authorized use from unauthorized use. Review logs and usage patterns for each key in the Console. Use separate keys for development, testing and production, so usage maps to one purpose and a compromise means disabling only that one. The Admin API returns each key's expires_at from List API Keys and Retrieve API Key, so you can audit keys and rotate them ahead of expiry. Identity-backed keys also make it clear which user or service account made each call.
Checkpoint 8 of 8· Exam question
A compliance auditor asks an engineering team to produce evidence of which Claude API keys are nearing expiration across all workspaces, so stale credentials can be rotated proactively before they lapse. Which action retrieves this information programmatically?
Correct answer: A — Call the Admin API's List API Keys endpoint with an Admin API key and inspect each returned key's `expires_at` timestamp, treating a `null` value as a key with no expiration.
- A. Correct. The Admin API's List API Keys endpoint returns each key's expires_at timestamp directly (null for keys without an expiration), which is exactly the audit signal needed.
- B. Incorrect. The Compliance API's Activity Feed logs events but does not report expiration timestamps, and 30 days is not a fixed or reliable default expiration to assume.
- C. Incorrect. Usage and cost data reflects consumption, not credential lifecycle; a zero-cost line item has no relationship to key expiration.
- D. Incorrect. Rate limits are not automatically tied to a key's expiration status; the Rate Limits API has no such behavior.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Removing an engineer from the organization revokes every API key they created.Why is that wrong?
Removal archives their personal keys, but a legacy workspace key belongs to the workspace and keeps working until it expires, is disabled or deleted, or the workspace is archived.
Covered in Key types and whose identity a key carries
2.A 403 from the Admin or Compliance APIs means the key is invalid and should be replaced with a fresh one of the same kind.Why is that wrong?
A 403 means the key authenticated but lacks the level the endpoint needs. Scopes are fixed at creation, so the fix is a new key carrying the missing scopes, not a re-issue of the same one.
Covered in Key types and whose identity a key carries
3.An expired key can be reactivated, or have its expiration extended, from the Console.Why is that wrong?
Expiration is fixed when the key is created. An expired key returns 401 and can't be reactivated, so you have to create a new key.
Covered in Storing, expiring and rotating keys
4.Deleting a suspect key is reversible, the same as disabling it.Why is that wrong?
Disable can be undone with Re-enable. Delete is permanent: the key is archived and only kept on record.
Covered in Detecting a leak, shutting it down and watching usage
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Personal keys and service account keys are identity-backed: each belongs to a user or service account your organization already manages”
↩︎ Key types and whose identity a key carries“A shared personal key acts as one person and breaks when they leave.”
↩︎ Key types and whose identity a key carries“The legacy x-api-key: YOUR_API_KEY header is still supported in place of Authorization.”
↩︎ Key types and whose identity a key carries“After a key expires, requests made with it return a 401 authentication_error.”
↩︎ Key types and whose identity a key carries“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.”
↩︎ How the API verifies which workspace a key can act in“The Admin API accepts a personal key or service account key only if the key isn't scoped to a specific workspace.”
↩︎ How the API verifies which workspace a key can act in“If your organization has a maximum expiration policy, the Console limits presets and custom durations to the policy maximum, and Never is unavailable.”
↩︎ Storing, expiring and rotating keys“7 days before expiration for keys created with a lifetime of at least 14 days”
↩︎ Storing, expiring and rotating keys“the Admin API reports each key's expires_at timestamp on the List API Keys and Retrieve API Key endpoints”
↩︎ Detecting a leak, shutting it down and watching usage“When that identity is removed from the organization, the key stops working.”
↩︎ Key concept“It expires, is disabled or deleted, or its workspace is archived, regardless of whether its creator leaves the organization”
↩︎ Exam trap 1“Create a new key to restore access; expired keys cannot be reactivated.”
↩︎ Exam trap 3“Expired keys can only be deleted.”
↩︎ Exam trap 4“It expires, is disabled or deleted, or its workspace is archived, regardless of whether its creator leaves the organization”
↩︎ Checkpoint“Confirm that requests succeed, then delete the workspace key on the API keys page.”
↩︎ Checkpoint“the key's user or service account doesn't have access to it, the API returns a 404 not_found_error”
↩︎ Checkpoint“expiration is set at creation time and cannot be changed afterward”
↩︎ Checkpoint“Disable is reversible (the Admin API reports the key's status as "inactive", and Re-enable returns it to "active")”
↩︎ Checkpoint - 2.
“A call that exceeds the key's scopes returns 403 Forbidden”
↩︎ Key types and whose identity a key carries“Scopes are fixed at creation; to add a scope later, create a new key.”
↩︎ Key types and whose identity a key carries“Organization members with the admin role”
↩︎ Key types and whose identity a key carries“A key created in one organization cannot be used to manage a different organization.”
↩︎ Key types and whose identity a key carries“A call that exceeds the key's scopes returns 403 Forbidden”
↩︎ Exam trap 2 - 3.
“developer | Can use playground and manage API keys”
↩︎ Key types and whose identity a key carries - 4.https://support.claude.com/en/articles/9767949-api-key-best-practices-keeping-your-keys-safe-and-secureOfficial docs
“In cloud environments, prefer encypted secret storage instead of dotenv files.”
↩︎ Storing, expiring and rotating keys“you are giving the developer of that tool access to your Claude Console account”
↩︎ Storing, expiring and rotating keys“Regularly rotate your API keys on a consistent schedule (for example, every 90 days) by creating new ones and deactivating old ones.”
↩︎ Storing, expiring and rotating keys“To prevent potential abuse, Anthropic automatically deactivates the exposed API key.”
↩︎ Detecting a leak, shutting it down and watching usage“These limits act as a safeguard against unexpected usage due to leaked keys or errant scripts.”
↩︎ Detecting a leak, shutting it down and watching usage“If your API Key is compromised, this allows you to quickly disable just that use case and limit any potential damage.”
↩︎ Detecting a leak, shutting it down and watching usage - 5.https://support.claude.com/en/articles/8384961-what-should-i-do-if-i-suspect-my-api-key-has-been-compromisedOfficial docs
“If you suspect that your API key may be compromised, we recommend revoking the key immediately.”
↩︎ Detecting a leak, shutting it down and watching usage