A credential should have a small blast radius.

An API key is copied into a deployment variable, used by one service, and forgotten because it keeps working. Six months later that service has changed owners, the key is shared by three workloads, and nobody can say what would stop if it were revoked. Rotation at that point is not maintenance. It is an incident with a calendar invitation.

API key rotation matters, but it answers only how long one secret remains valid. Scoped API credentials answer the harder question: what can this secret reach while it is valid, and what is the maximum consequence if it leaks?

The useful unit is not “a key for the company.” It is one credential for one workload, in one environment, with one declared set of actions. That boundary makes routine rotation possible, revocation surgical, and the audit trail intelligible.

Rotation and scope solve different failures

A broad key rotated every 30 days is still broad on every one of those days. A narrowly scoped key that never expires eventually becomes an orphan. Good credential design needs both controls because they contain different dimensions of risk:

• Scope limits capability — which surfaces and actions the credential can invoke.
• Environment limits placement — a test credential should not authenticate against production.
• Workload identity limits sharing — one label and one owner identify exactly what depends on the key.
• Rotation limits age — the time a copied secret remains useful without being replaced.
• Revocation limits response time — how quickly access can be stopped once exposure or misuse is suspected.

These are concentric boundaries, not substitutes. If any one is missing, the other controls have to carry a risk they were not designed to contain.

Start with a workload, not an administrator

Credential inventories often begin with the person who created the key. That is useful provenance and poor ownership. People move teams; workloads keep running. Name a key after the service and purpose that consume it, then attach a human owner and a review date as metadata.

A concrete model for a portal integration might look like this:

The point is not the names. It is the negative space: the review should be able to state what each key cannot do. “Read and write” is a feature description. “Can create a collection link but cannot read the documents submitted through it” is an access boundary.

Read the enforcement boundary, not the scope name

A scope printed in a dashboard is not evidence that every endpoint enforces it. The enforcement point lives in code, and products frequently add named scopes one surface at a time.

Cogneris documents this boundary directly in the authentication reference. Portal operations and the separate content-management surface enforce their declared scopes. The document endpoints currently accept any valid tenant key and do not inspect the scope list. An empty explicit scope list also produces the wildcard *, not “no access.”

That detail changes the architecture. You cannot honestly describe a key as “document-read-only” if the document surface does not enforce that distinction. Until enforcement exists, contain the key with the controls that are real: separate it by workload and environment, keep it server-side, avoid sharing it across services, and treat access to its secret store as access to the whole document surface for that tenant.

Least privilege is not the list you requested. It is the intersection between the list and what the service actually rejects.

A rotation without downtime has four states

“Replace the key” hides a distributed-systems change. Deployments roll, queues drain, workers restart at different times, and a secret manager update is not proof that every process has reloaded the value. A safe cutover needs an overlap window and observable states:

1. Mint — create a second credential with the same intended boundary and a distinct identifier.
2. Deploy — update the secret reference, restart or reload every consumer, and record the deployment that carried the new key.
3. Observe — verify successful requests made by the new credential and verify that usage of the old credential has fallen to zero across a complete workload cycle.
4. Revoke — disable the old key, run a canary request through the workload, and retain the revocation event as evidence.

Cogneris permits two active keys per label during this cutover. That overlap is a migration mechanism, not permission to leave twins alive indefinitely. Give it an expiry, an owner, and an alert when the old credential is still used after the expected drain time.

Revocation is a testable behavior

A button labelled “revoke” is an intention. The contract is what the next request does. The Cogneris authentication reference states that a revoked key returns 401 on the next request, without propagation delay. That makes the post-revocation check straightforward: use the retired key once against a harmless endpoint, expect 401, then prove the replacement still succeeds.

Do not confuse authentication and authorization failures during the test. A 401 means the token is missing, malformed or revoked. A 403 means the token remains valid but lacks the scope for that operation. Those outcomes tell different stories, and an automated rotation should stop when it sees the wrong one.

Emergency revocation uses the same mechanics with a different order. When exposure is suspected, revoke first and repair availability second. A planned rotation protects uptime; an incident response protects the boundary.

Secret storage is part of the credential design

A scoped key pasted into source code is still a leaked key. A rotated key delivered through an unencrypted build log is already old before the deployment completes. The storage path has to preserve the boundary created at issuance.

• Keep credentials server-side — a browser bundle, mobile binary or public configuration endpoint cannot keep a shared secret.
• Reference, do not copy — let workloads retrieve a versioned secret from a secrets manager or encrypted CI variable rather than duplicating it across configuration files.
• Separate services — one key reused by five services turns one revocation into a five-team outage and makes attribution impossible.
• Redact by shape — scanning for known credential prefixes catches accidental logs and commits earlier than a human review.
• Restrict the delivery path — whoever can edit the deployment secret can change which credential the workload uses, even if they cannot mint a new one.

Rotation frequency is secondary to this path. A secret that is exposed on every deployment does not become safer because it changes more often.

This is not agent governance

“Scope” also appears in agent governance, but the object being bounded is different. Our proportional agent governance article scopes the tools and decisions an agent may use according to its autonomy and blast radius. Our agent lifecycle article makes the agent itself an owned asset with a sponsor, review date and decommissioning gate.

This article sits one layer lower. It asks what an API credential authorizes regardless of whether the caller is an agent, a batch job, an integration service or a person at a terminal. Revoking an agent's key is one step in retiring the agent; it is not the lifecycle policy. Conversely, a well-governed agent with a wildcard credential still has an unnecessarily large technical blast radius.

This is not webhook verification either

An API key proves that your caller may send a request to a service. A webhook signature lets your receiver verify that an inbound callback was signed by the expected sender and that the raw payload was not changed. They travel in opposite directions and fail under different threat models.

The signing secret, timestamp tolerance and retry behavior belong to the webhook callback contract. Do not reuse an API key as a webhook signing secret, and do not treat successful signature verification as permission for the payload to perform any downstream action. Authentication of the message and authorization of the consequence remain separate gates.

Measure the boundary, not just the rotation date

• Credential age — time since issuance, segmented by environment and workload rather than averaged across the estate.
• Shared-consumer count — how many independently deployed workloads use the same key. The target is one.
• Wildcard share — the proportion of active credentials with * or an equivalent unrestricted grant.
• Old-key drain time — time from replacement deployment to the last successful request made by the retiring key.
• Revocation verification — whether a denied canary and a successful replacement canary were recorded after each cutover.
• Unknown-owner count — credentials whose consuming workload or accountable human cannot be named.

A fleet can have 100% “rotated on time” and still fail every other measure. That is how a hygiene metric becomes a security story it never proved.

Seven questions before you mint the key

1. Which single workload will use this credential?
2. Which environment accepts it, and can another environment reject it?
3. Which exact operations are enforced by its scopes, and which are not?
4. What can the workload explicitly not do?
5. How will a second key be deployed and observed before the first is revoked?
6. What proves revocation took effect?
7. Who owns the workload, the review date and the emergency decision?

A credential is not small because the string is hidden. It is small when the system around it can name its workload, enforce its reach, replace it without guessing, and stop it without taking unrelated services down.