All chapters
  1. Start hereA valid token is not a permission
  2. Foundations · 1Identity and trust primitives: who is calling, and who checks
  3. Foundations · 2People and identity proofing: accounts, passwords and recovery
  4. Foundations · 3Sessions and browser security: cookies, CSRF, XSS and the BFF
  5. Foundations · 4Authenticators and MFA: passwords, passkeys and phishing resistance
  6. Foundations · 5API keys and application credentials: what a key proves
  7. Foundations · 6Tokens: bearer, JWT anatomy, validation and revocation
  8. Foundations · 7OAuth, OpenID Connect and federation: delegation and login
  9. Authorization · 8Authorization from first principles: subject, action, resource, context
  10. Authorization · 9Access control models: RBAC, ABAC, ReBAC and ownership
  11. Authorization · 10The enforcement architecture: PEP, PDP, PIP and PAP
  12. Authorization · 11Policy as code: versions, tests, engines and decision logs
  13. Authorization · 12Tenant and data isolation: one platform, many brokerages
  14. Authorization · 13Identity governance and lifecycle: joiner, mover, leaver
  15. Authorization · 14Privileged access: standing rights, just-in-time elevation and break-glass
  16. Workloads · 15TLS, PKI and certificates: proving a host, and a client
  17. Workloads · 16Workload and service identity: SPIFFE, mTLS and caller allowlists
  18. Workloads · 17API gateways and zero trust: the edge checks, the service decides
  19. Workloads · 18Event-driven identity: Kafka principals, ACLs and replay
  20. Workloads · 19Cloud IAM and secretless deployment: roles, federation and no stored keys
  21. Workloads · 20External SaaS, webhooks and trust: calls that cross company lines
  22. Workloads · 21Private controlled environments: what private networking does and does not secure
  23. AI-native · 22Authenticating to model providers: keys, gateways and cloud IAM
  24. AI-native · 23MCP identity and authorization: discovery is not permission
  25. AI-native · 24RAG and retrieval authorization: only what this caller may read
  26. AI-native · 25Agents as principals and delegates: whose authority is this?
  27. AI-native · 26Agent-to-agent trust: identity, capabilities and forwarded authority
  28. AI-native · 27Coding agents and CI: repository scopes, OIDC and no production keys
  29. Operations · 28Auditing and observability of access: decisions you can prove later
  30. Operations · 29Threat modeling and testing: the negative tests that prove access control
  31. Operations · 30Operational lifecycles: rotation, revocation and outages
  32. Reference · 31Standards, frameworks and products: what each one is, and what it is not
  33. Reference · 32Architecture decision playbooks: choosing an auth strategy
  34. ReferenceGlossary
  35. AboutAbout this site and its sources
Foundations · 5

API keys and application credentials: what a key proves

An x-api-key header is a naming convention, not a protocol. What a key identifies, restrictions, rotation and revocation, leakage, client id versus secret, and when a key is a reasonable production choice.

You will understand
What an API key identifies: a calling application or account, never the person behind a request.
You will be able to decide
When a key is a reasonable production choice, and what would make you replace it.
You will keep apart
A client_id (a name, not a secret) and the secret that proves it, and both from a permission.

The assessment service needs roof data. For series case UW-004, property PROP-2207 says 9 years on the application; the roof data provider, an outside vendor, reports 22 years under evidence EV-ROOF-0412, and that gap is what rule R-ROOF-03 escalates. The vendor's onboarding email contains one long string and a sentence: send this in the x-api-key header.

In the design review an engineer offers the shortest path. The underwriting agent already decides when it needs roof data. Put the key in the agent's tool configuration, let the tool call the vendor directly, and skip the assessment service. One fewer hop, nothing new to deploy.

That proposal is the mistake this page is about, and it is not that API keys are bad. The vendor only offers keys, and a key is a perfectly workable credential for one server calling another. The mistake is where the key would live. Anything in a tool configuration that the agent application loads can end up in a prompt, a log, a trace or a model's output, and the key would then be readable by everyone who can read those. The key must stay where only the code that uses it can reach it. The questions of this page follow from that scene: what does this string prove, to whom, and who can get a copy?

What an API key is, and what it is not#

An API key is a long random string that a service issues to a calling application. Whoever presents the string is treated as that application, or as the account that created it. Nothing else is proven. A tiny example: the roof data provider sees the key on a request and knows "this is the insurer's account, bill it and apply its quota". It does not know which underwriter, which agent or which submission the request is for.

That narrowness is in the providers' own documentation. Product (Google Cloud API keys, as documented on 2026-11-18): a standard key links a request to a project for billing and quota, and "the API key doesn't identify a principal", so IAM cannot check whether the caller is authorized; a separate kind, the authorization key, is "bound to a service account". Guideline (OWASP API Security Top 10 2023, API2, read 2026-11-18): do not use API keys for user authentication; use them only for API client authentication. Guideline (OWASP REST Security Cheat Sheet, read 2026-11-18): "Do not rely exclusively on API keys to protect sensitive, critical or high-value resources."

The header name carries no meaning either. x-api-key is a naming convention: an HTTP header someone chose, defined by no standard, that each provider documents for itself. Some providers have moved away from it. Product (Claude API, as documented on 2026-11-18): requests authenticate with Authorization: Bearer <token>, where the token is an API key or a short-lived token from Workload Identity Federation; x-api-key is a "Legacy fallback for Authorization, still supported".

Plain English. An API key is a password for a program. It says which account is calling. It never says which person, and it never says which record that account may touch.
Before AI. Every backend engineer has handled this credential under other names: the database password in application.properties, the SMTP account a mail job logs in with, the service account password for an LDAP bind. The lessons are the same ones teams learned there. Keep it out of the repository, give it the fewest rights that work, rotate it without an outage, and know who has a copy.

client_id and secret: a name and its proof#

OAuth splits the two parts of a key into separate fields, and the split is worth borrowing as a way of thinking. A client_id is a public name for a registered application. Standard (RFC 6749 §2.2, read 2026-11-18): "The client identifier is not a secret" and "MUST NOT be used alone for client authentication." A client secret is the shared secret that proves the application holds that name. Standard (RFC 6749 §2.3.1): the client_secret parameter carries it; clients "MAY use the HTTP Basic authentication scheme", and sending it in the request body "is NOT RECOMMENDED".

Most API keys bundle both parts into one string. That is why a good key design gives the key a visible identifier part that can be logged and shown in a console, and a secret part that is shown once and never stored in clear. It is also why current OAuth guidance prefers something stronger than a shared secret. Standard (RFC 9700, read 2026-11-18): authorization servers "SHOULD enforce client authentication if it is feasible", and "It is RECOMMENDED to use asymmetric cryptography for client authentication", such as mutual TLS or private_key_jwt. With a private key, the server holds only a public key, so a leak of the server's records gives an attacker nothing to replay.

The smallest primitive: issuing and checking a key#

The code below shows the issuer's side of an API key in its smallest credible form. It demonstrates four decisions: a key has a public id and a secret; only a hash of the secret is stored; each key carries restrictions and an expiry; and the check answers "which application is this?" and nothing more. It is a minimal shape for teaching, not part of examples/uw-auth/, and it leaves out rate limits, audit events and storage. In production, use the key management of your API gateway or identity provider, or a maintained library.

import hashlib
import hmac
import secrets

# What the issuer stores per key: an id you can show, a hash, an owner, restrictions, an expiry.
KEYS: dict[str, dict] = {}


def issue_key(owner: str, apis: list[str], expires_at: int) -> str:
    key_id = "k_" + secrets.token_hex(4)                 # public part: safe to log and to show in a console
    secret = secrets.token_urlsafe(32)                    # 32 random bytes; shown once, never stored
    KEYS[key_id] = {"owner": owner, "apis": apis, "expires_at": expires_at, "revoked": False,
                    "sha256": hashlib.sha256(secret.encode()).hexdigest()}
    return key_id + "." + secret                          # the caller sends this in a header


def check_key(presented: str, api: str, now: int) -> dict:
    key_id, _, secret = presented.partition(".")
    rec = KEYS.get(key_id)
    if rec is None or rec["revoked"] or now >= rec["expires_at"]:
        return {"ok": False, "status": 401}
    if not hmac.compare_digest(rec["sha256"], hashlib.sha256(secret.encode()).hexdigest()):
        return {"ok": False, "status": 401}
    if api not in rec["apis"]:                            # restriction: which API this key may call
        return {"ok": False, "status": 403}
    return {"ok": True, "status": 200, "caller": rec["owner"], "key_id": key_id}

Notice what a successful check returns: caller and key_id. That is identification plus authentication of an application, and the restriction says which API it may call. Nothing in it says which quote or which submission. The Python documentation describes the secrets module as suited to "security tokens, and related secrets" and states that 32 bytes of randomness is believed sufficient for typical use. A fast hash is acceptable here, unlike for passwords, because the secret is long and random rather than chosen by a person; that is this site's reasoning, explained in the folded notes below.

Two keys in the insurance example#

The example has two keys, and they teach opposite lessons. One is a mistake shown on purpose; the other is the correct design.

The labelled mistake: a key where a person's token belongs#

Suppose the broker portal backend (svc-portal-bff) called the quote API with its own API key instead of the broker's access token. The key is valid; the API gateway accepts it. But the quote service now has a request from "the portal application", with no broker in it. It cannot apply the rule "a broker reads quotes of its own tenant", because there is no broker and no tenant.

The hops lab shows the four hops for this request. Choose the API key toggle, then add the gateway-only toggle and pick the other tenant's quote.

For a reader without JavaScript, here is the same data from services.py request_path, run in a scratch copy of the example. First with the key alone, for the broker's own quote Q-5531:

HopCredential presentedSubjectDecisionDecided by
1 callerx-api-key of svc-portal-bffsvc-portal-bff (the application)sendsnobody
2 gatewayx-api-keysvc-portal-bffpasssvc-api-gateway
3 servicex-api-keysvc-portal-bffdeny 403pdp R-AZ-00
4 databasenonenonenot reachednobody

The quote service refuses with 403 and the reason "a key identifies the calling application, not the broker: no rule lets this principal quote.read: deny by default". The lesson printed by the function: "An API key authenticates the application. Per-broker access needs the broker's identity in the request." Now the same key with the service trusting the gateway (no object check), asking for Q-6620, which belongs to brk-south:

HopCredential presentedSubjectDecisionDecided by
1 callerx-api-key of svc-portal-bffsvc-portal-bff (the application)sendsnobody
2 gatewayx-api-keysvc-portal-bffpasssvc-api-gateway
3 servicex-api-key (checked at the gateway)svc-portal-bffno object checknobody
4 databaseservice account of svc-quotesvc-quoterows: 1nobody

Outcome: status 200, data returned, leaked: True. "An application key plus a gateway check returns any quote the application asks for: no broker identity, no object check." The first table shows deny by default doing its job; the second shows what happens when a key stands in for a person and nobody checks the record. A valid token is not a permission, and a valid key is not one either.

The correct design: the vendor key stays in the assessment service#

The vendor key is the opposite case. The roof data provider has no idea who the insurer's underwriters are, and it should not need to: the insurer decides who may see roof data for which submission. The vendor only needs to know which customer account is calling. An API key answers exactly that question, so here a key is a reasonable production choice.

What makes it safe is where it lives and who can use it. In the example the key sits in a secrets-store stand-in inside the assessment service. Callers get the result of using the key, never the key. From examples/uw-auth/services.py, verbatim:

class SecretsStore:
    """Secrets-manager stand-in. Callers get the RESULT of using a secret, never the secret."""

    def __init__(self) -> None:
        self._secrets = {"roof-vendor": "DEMO-VENDOR-KEY-NOT-A-SECRET-teaching-only"}
        self.uses: list[str] = []

    def call_vendor(self, name: str, property_id: str) -> dict[str, Any]:
        """Use the vendor key inside the store boundary; return only the vendor's data."""
        _key = self._secrets[name]           # used here, never returned
        self.uses.append(name)
        if property_id == "PROP-2207":
            return {"roof_age_years": 22, "evidence_id": "EV-ROOF-0412", "source": "roof data provider (stand-in)"}
        return {"roof_age_years": None, "evidence_id": None, "source": "roof data provider (stand-in)"}

The key string says what it is: a teaching value, not a secret. The order of operations is the important part. get_roof_assessment first asks the policy decision point whether this caller may read the assessment for this submission, and only then calls call_vendor. Running it in a scratch copy for the underwriter u-uw-w1 and SUB-1004, then scanning the response and the audit log for the key string:

status: 200 rule: R-AZ-04
body: {"submission_id": "SUB-1004", "property_id": "PROP-2207", "roof_age_application_years": 9, "roof_age_provider_years": 22, "evidence_id": "EV-ROOF-0412"}
secret uses: ['roof-vendor']
key string in response or audit log: False

The underwriter receives roof ages and an evidence id. The key was used once and appears nowhere outside the store. When the underwriting agent needs roof data, it calls the tool get_roof_assessment; the agent application sends that request with the agent's own credential; the assessment service validates it, asks the policy decision point, and uses the key. The model never sees the key, because no part of the path hands it over. The agent here is a scripted stand-in, so these results show how the access controls work, not how good any model is.

Diagram: Where the roof vendor key lives · rejected design against the example's design

The top lane is the rejected design: the key sits in the agent's tool configuration, so it travels into every prompt, trace and log that configuration reaches. The bottom lane is the example's design. The agent application sends get_roof_assessment with the agent's own credential; the assessment service asks the PDP whether this caller may read the assessment for SUB-1004; only then does the secrets store use the key to call the vendor, and only roof data comes back. The key never leaves the store.

  1. Rejected: key in the tool configuration
    1. key in agent tool configuration: A credential placed on a path built for sharing: configuration is assembled into context and copied into traces.
    2. copied to prompts, traces, logs: Every store that holds model input now holds the key in clear.
    3. vendor sees the insurer's account: The vendor cannot tell a legitimate call from a call by whoever copied the key.
  2. The example: key stays in the assessment service
    1. agent application sends get_roof_assessment: The model writes the request; the agent application sends it with the agent's credential, never with the vendor key.
    2. assessment service asks the PDP: The service decides whether this caller may read the assessment for this submission before any vendor call.
    3. secrets store uses the key, returns data: SecretsStore.call_vendor uses the key inside its boundary and returns only the vendor's data.
    4. response + audit without the key: The run shows the key string in neither the response nor the audit log.

The diagram puts the two designs side by side. In the rejected design the key travels with the agent's tool configuration, so every place that configuration reaches (prompts, traces, logs) becomes a place the key can leak from. In the chosen design the key never leaves the assessment service's secrets store, and the authorization decision happens before the key is used.

What this is not. The credential for the model provider itself (the LLM gateway's key or cloud identity) has its own page, Model providers. Signing secrets for webhooks and outbound OAuth to vendors are on External SaaS and webhooks. Secrets managers and keyless cloud identity are on Cloud IAM.

Restrictions, rotation and revocation#

A key that works for everything, from anywhere, forever, is the worst version of a reasonable credential. Three controls shrink it.

A key restriction limits where and for what a key works. Product (Google Cloud, as documented on 2026-11-18): API restrictions limit a key "to only be used with a specific set of APIs"; application restrictions limit it to websites, IP addresses, Android apps or iOS apps; "Unrestricted API keys are insecure", and Google recommends setting both kinds. The same page warns that for Android and iOS restrictions, "Bypassing this restriction is straightforward." A restriction that rests on something the client says about itself is a speed bump; one that rests on the network path (an IP allowlist for a server) is stronger. Product (Claude API, as documented on 2026-11-18): keys can be scoped to a single workspace and IP allowlisting is available.

Key rotation is replacing a key with a new one without an outage. The pattern is an overlap: issue the new key, deploy it everywhere, watch the old key's use fall to zero, then revoke the old key. Product (Google Cloud): "By periodically rotating your API keys, you can limit the impact of any compromised API keys"; delete the old key once all applications use the new one. Product (Claude API): the expiration is chosen when the key is created and "cannot be changed later"; expired keys return 401 authentication_error. An expiry set at creation forces rotation to be practised rather than promised.

Revocation is the emergency version. Guideline (OWASP Secrets Management Cheat Sheet, read 2026-11-18): "Keys that were exposed should undergo immediate revocation", and "Secrets revoked/rotated must be removed from the exposed system immediately". A system that cannot revoke a key in minutes, because nobody knows which services use it, has a key it cannot afford to leak.

Diagram: Life of the vendor key · issue, restrict, store, rotate, revoke, detect

Read left to right. The key is issued with an expiry and restricted by API and network before it is stored. Only the assessment service reads it from the secrets manager. Rotation issues a second key, moves traffic, and revokes the first once its use reaches zero. Leak detection (secret scanning, provider notices) feeds the same revocation step, which is why knowing every user of a key matters before the leak, not after.

  1. Issue
    1. vendor issues key with an expiry: The vendor creates the key for the insurer's account. If the vendor supports an expiry, set one at creation.
    2. restrict by API and by network: Limit which vendor APIs the key may call and from which addresses, where the vendor supports it.
  2. Keep
    1. secrets manager, one reader: The key lives only in the secrets manager; one workload may read it, and every read is audited.
  3. Rotate
    1. second key, overlap: Issue the new key and store it as a new version while the old one still works.
    2. old key use reaches zero: Confirm in the vendor's usage view that no traffic uses the old key.
  4. Revoke
    1. revoke at the vendor: Revocation ends the old key. On a leak it comes first, before investigation.
    2. leak signal: scanning, notices: Secret scanning on repositories, provider notifications and log scans trigger the same revocation.

The lifecycle diagram shows the loop for the vendor key: issued with restrictions, stored in the secrets manager, used only by the assessment service, rotated with an overlap, and revoked on a schedule or on a leak signal. The leak signal is the step most teams leave out.

Secret leakage: how keys escape, and how you find out#

Secret leakage is a credential reaching a place where people or systems that should not hold it can read it. Keys escape in boring ways: committed to a repository, pasted into a ticket, printed in a log line, put in a URL. Guideline (OWASP REST Security Cheat Sheet, read 2026-11-18): "Passwords, security tokens, and API keys should not appear in the URL, as this can be captured in web server logs." In an agent system there are new places: a prompt, a tool definition, a retrieved document, a trace of the model's input. Each of those is copied, stored and shown to people for debugging.

Detection is possible because keys have shapes. Product (GitHub secret scanning, as documented on 2026-11-18): it "scans your entire Git history on all branches of your repository for hardcoded credentials", plus issues, pull requests, discussions and wikis; when a partner's secret is detected, "we notify the provider so they can take action, such as revoking the credential"; it runs automatically and free for public repositories, while private repositories need GitHub Secret Protection. Guideline (OWASP Secrets Management): enable detection "at the developer level to avoid checking secrets into code before commit/PR".

Development keys deserve the same care. A development key for the roof data provider still bills the insurer's account, still returns real vendor data, and is usually less watched. Product (Google Cloud, as documented on 2026-11-18): holding a service account key is "similar to knowing a user's password", and leaked keys matter because service accounts "are not subject to any additional sign-in verifications". That sentence is about one product's keys; the reasoning holds for any key.

In a coding agent. A coding agent works in a sandbox with no production credentials, so there is nothing to paste into a commit. If a developer pastes a key into a file the agent edits, secret scanning on the repository is the net. CI reaches the cloud through OIDC federation instead of a stored key, so there is no long-lived cloud key to leak in the first place. The Coding agents page owns this case.

Failure mode: the key in the tool configuration#

Return to the design review, and follow the rejected design one step further as a labelled mistake. The key is placed in the agent's tool configuration. The agent application includes tool configurations in the context it assembles for each run, so the key reaches the model provider with every request. A developer turns on full prompt tracing to debug a failed run; the trace store now holds the key in clear, readable by everyone with trace access. Months later the key is found in a support ticket that quoted a trace.

Nothing in that chain was an attack. Each step was ordinary engineering: include configuration, trace inputs, quote a trace. The defect was placing a secret on a path built for sharing. The fix is the design the example uses: the key lives in a secrets store inside the one service that needs it, that service authorizes the request before using it, and model-visible context never contains a credential.

Architecture choice: when a key is enough#

API keys are not categorically wrong in production. The risk depends on what the key can reach, how long it lives, and whether a person's authority is involved.

SituationSimplest credible optionGrow whenAlternatives
Server calls a vendor that only offers keys (the roof data provider)Restricted key in a secrets manager, used by one service, rotated with overlapThe vendor offers OAuth client credentials or signed requestsOAuth client credentials; mutual TLS
Server calls a cloud API that supports workload identityDo not create a key: use the workload's cloud identityn/aShort-lived keys derived from an IAM principal
Public, low-sensitivity data with quotasKey for metering and rate limitsData becomes per-customerOAuth client credentials
Per-user data (a broker's quotes)Never a key alone: the person's token, with an object check on the recordn/aSee Tokens and OAuth and OIDC
A model provider for an agentLLM gateway holds the provider credentialSeveral teams share modelsCloud-managed models through IAM; see Model providers

The second row deserves a sentence of its own. Product (Amazon Bedrock, as documented on 2026-11-18): short-term API keys inherit "permissions from the IAM principal used to generate it" and are "Recommended for production use", while long-term keys create an IAM user and are "Recommended only for exploration". Product (Azure OpenAI classic RBAC page, as documented on 2026-11-18): "using API keys will bypass the Azure RBAC access control". When a platform offers identity-backed access, a static key is usually the weaker of the two paths.

This site's recommendation: use a key when the other side offers nothing better and the key identifies your application to that side only; keep it in a secrets manager inside one service; restrict it by API and network; set an expiry; and scan for it. Never let a key replace a person's identity, and never let it reach model-visible context.

Standards and products for this chapter#

There is no API key standard. Standard (RFC 6749): client identifier and client password. Standard (RFC 9700, BCP 240): current OAuth security advice, including asymmetric client authentication. Guideline (OWASP REST Security, Secrets Management, API2 Broken Authentication): read 2026-11-18. Product (as documented on 2026-11-18): Google Cloud API keys, Claude API authentication, Amazon Bedrock API keys, GitHub secret scanning. None of these products was run here; key management in identity providers and gateways is compared on Frameworks.

Security notes#

Security note. Store only a hash of keys you issue, show the secret once, and log the key id, never the key.
Security note. Return 401 for an unknown, expired or revoked key and 403 for a valid key used outside its restrictions, and rate-limit both. OWASP's REST sheet adds: revoke keys on violation, 429 for excess requests.
Production pitfall. A key that "only works from our servers" because of an IP allowlist stops working from a new region or egress address. Put the allowlist in the same change process as network changes, or the first outage teaches the team to remove it.

Monday checklist#

  1. Inventory every key you hold and every key you issue: owner, purpose, restrictions, expiry, last use.
  2. Grep prompts, tool configurations and trace stores for key-shaped strings; move any hit into a secrets manager and rotate it.
  3. Turn on secret scanning for every repository, and a pre-commit check for developers.
  4. Add API and network restrictions and an expiry to each key that lacks them.
  5. Practise one rotation with overlap on a non-critical key, and time how long revocation takes.
  6. Replace keys with workload identity wherever the platform supports it.

Exercises#

  1. A partner asks to call the quote API with an API key "for their brokers". What do you answer?
AnswerThe key names the partner, not the broker

A key can identify the partner's application, but each request must also carry the broker's identity (a token from federation), and the quote service decides on the record. A key alone makes every broker look like the partner.

  1. Is a client_id in a mobile app's source a leak?
AnswerNo; a client secret there would be

RFC 6749 says the client identifier is not a secret. A client secret in a mobile app cannot stay confidential, which is why such apps are public clients and use PKCE instead.

  1. Secret scanning reports the roof vendor key in a two-year-old commit on a feature branch. The branch is deleted. Done?
AnswerRevoke first

No. Treat the key as exposed: rotate to a new key, revoke the old one at the vendor, check the vendor's usage records for the exposure period, then clean the history.

Advanced perspective#

Storing issued keys: why a fast hash is acceptable hereEntropy decides, not the word "secret"

Passwords need slow hashes because people choose them from a small space that attackers can enumerate. An issued key built from 32 random bytes has a space no one can enumerate, so a leaked table of SHA-256 hashes does not let an attacker recover the keys, and a fast hash keeps the check cheap on every request. That is this site's reasoning from the entropy argument; it holds only if the issuer generates the key, never lets a person pick it, and uses a cryptographically strong source such as Python's secrets module.

The visible key id does a second job: lookup. The server finds the record by id and compares one hash, instead of hashing against every stored key. Prefixes that name the issuer and the key type also help secret scanners recognise your keys, which is how partner programs notify an issuer about a leak.

Keys you hold from vendors are the opposite case: you must be able to send them, so you cannot store only a hash. That is what a secrets manager is for, with access limited to the one workload that calls the vendor, and audit on every read.

Rotation without an outageTwo valid keys, one cut-over, evidence before revocation

Zero-downtime rotation needs the other side to accept two keys at once; check that in the vendor's documentation before signing. If a vendor allows only one active key, rotation means a coordinated cut-over and a short window of failures, and that limitation belongs in the vendor review.

The steps for the roof vendor key: create the new key at the vendor; write it to the secrets manager as a new version; let the assessment service pick up the new version (on restart or on a refresh interval); confirm in the vendor's usage view that the old key's traffic has stopped; revoke the old key. The secrets manager's rotation features can drive this. AWS Secrets Manager offers managed rotation and rotation by a Lambda function; Google Secret Manager sends a SECRET_ROTATE message to Pub/Sub and leaves the new version to your subscriber (both as documented on 2026-11-18). Neither creates the vendor's key for you unless the vendor integrates.

Measure rotation by revocation, not by issuance. A rotated key that stays valid in case it is needed again is a second key, and the inventory should show it.

When keys bypass the identity systemA second door next to the one you guard

Several platforms accept both identity-based access and keys. The Azure OpenAI (classic) documentation states that using API keys bypasses Azure RBAC. Google Cloud's authorization keys authenticate as a service account, so a key leak equals that account's permissions without any sign-in. In both cases a team can do careful role design and still leave a key path that ignores it.

The governance answer is an inventory per platform: which resources accept keys, who can create or read them, and whether key-based access can be turned off. The Azure page read here does not cover how to disable key authentication, and the Google page read here does not give the organization policy constraint ids; check those pages before writing the configuration. For new organizations Google enforces the constraints that disable service account key creation and upload by default (for organizations created on or after 3 May 2024, as documented on 2026-11-18).

Responding to a leaked keyRevoke, replace, investigate, clean

The order matters. Revoke or disable first, because every minute the key works is exposure; then deploy the replacement; then investigate with the provider's usage records for the window between the leak and the revocation; then clean the places the key leaked to. OWASP's Secrets Management sheet adds that secrets in logs need a removal process that keeps log integrity, which conflicts with append-only audit stores. The usual answer is to prevent keys reaching durable logs at all, with redaction at the point of logging (see Audit).

Provider-side detection helps but is not a control you can rely on. Google states it may disable leaked service account keys it detects, but "Google Cloud doesn't guarantee that it will detect leaked keys." GitHub's partner program notifies providers for supported secret types. Your own scanning and your own inventory are what make the response fast.

In one breath#

An API key identifies a calling application or account, and nothing about the person or the record behind a request. That makes it a reasonable production credential for one server calling another, such as the assessment service calling the roof data provider, when the key is restricted, held in a secrets store inside the one service that uses it, rotated with overlap and watched for leaks. It is the wrong credential wherever a person's authority must travel, and it never belongs in model-visible context.

The vendor key now stays inside the assessment service, and the portal no longer pretends a key is a broker. For the broker, the request has to carry something that names the person, says who issued it, for which API, and until when, in a form every service can check. That something is a token, and reading one correctly is the subject of Tokens.