Design API Credentials for Human Error

Security training helps people recognize suspicious requests and handle secrets carefully. It cannot be the only barrier between a mistake and unrestricted API access. A resilient credential design assumes that a person will eventually paste a token into the wrong terminal, approve a convincing prompt, commit a secret, or miss an alert.

NIST defines phishing resistance as preventing disclosure of useful authentication secrets to an impostor without relying on the user's vigilance; its current authenticator guidance explains why manually entered one-time codes are not phishing-resistant. CISA similarly recommends phishing-resistant MFA, bounded session durations, least privilege, and account review. Those principles protect human accounts. Machine credentials need an analogous design: least authority, short useful life, clear ownership, and fast revocation.

Reduce the value of a stolen token

An API token is usually a bearer secret: possession is enough to use it. Compensating controls should therefore limit what possession buys an attacker.

• Scope a token to one workload rather than one team.
• Set an activation ceiling so a forgotten loop or stolen token cannot run indefinitely.
• Add an expiry appropriate to the workload.
• Apply token or spend limits only where accounting is reliable and fails closed.
• Restrict source networks when requests originate from stable infrastructure.
• Keep production, development, and personal credentials separate.

Avoid putting the same long-lived provider key in laptops, CI, notebooks, and production. A single disclosure should not force an emergency rotation across every environment.

Make the safe path easier

People work around controls that make routine work impractical. Give developers a documented way to request a bounded credential, test locally, and obtain a replacement without copying a shared secret from a colleague. Prefer one-time display and a secure secret manager over chat, email, or a wiki.

Administrative accounts deserve stronger treatment than workload tokens. Require phishing-resistant authentication where the identity provider supports it, keep administrative sessions separate from day-to-day browsing, and review which people and automations can mint or revoke credentials.

Prepare for the predictable mistake

A credential incident runbook should be short enough to use under pressure:

1. Revoke or disable the exposed credential.
2. Determine its workload, permissions, limits, and exposure window.
3. Review provider and control-layer usage records without copying sensitive payloads into the incident record.
4. Replace the credential through the normal issuance path.
5. Look for the same secret in repository history, build artifacts, logs, tickets, and messages.
6. Fix the process that made disclosure easy.

Rotation is not revocation. Issuing a new credential while the old one still works leaves the immediate risk in place.

Use controls without overstating them

Till is a hosted beta that centrally manages encrypted AI-provider connections and issues provider-agnostic scoped tokens. Activation ceilings and optional constraints can reduce the blast radius of a leaked workload token, and per-key records can help identify unexpected use.

Till is not a phishing defense for human accounts, a secret manager for every system, or a compliance guarantee. Provider-side revocation, billing alerts, protected administrator access, host security, and incident response remain necessary.

The useful cultural message is not “be more careful.” It is “report mistakes quickly; the system is designed to contain them.” Training and blameless reporting matter most when the underlying credentials are already engineered to fail small.

← Back to blog