HASZB_AIHASZB_AI

Search across courses, lessons, glossary terms, prompts and tools.

Menu

Stage 7 · APIs, MCP & Connectors

Keys, scopes and rate limits

The operational half of integration — credentials that do not leak, permissions that stay narrow, and limits you handle instead of hitting.

6 min read

In this lesson

  • Handle API keys without exposing them
  • Scope credentials to the minimum needed
  • Handle rate limits and retries correctly

This is the unglamorous half, and it is where real systems break or leak.

Keys

An API key is a credential. Treat it exactly as you would a password.

Never in the frontend. Anything shipped to a browser is public. Minification is not protection — the key is in the bundle, readable by anyone who opens developer tools. Calls that need a secret go through your own server.

Never in version control. Keep them in environment variables, loaded from a file that is gitignored, or in a secrets manager. A key committed once is compromised even after you delete it, because it remains in history.

Never in a prompt. It becomes part of the conversation, gets logged, and may end up in stored history.

Rotate on exposure. If a key might have leaked, replace it. Deleting the message is not remediation.

Scopes

Most APIs let a key be restricted. Use it, every time.

  • Read-only when you only read. This removes an entire class of damage permanently.
  • Resource-scoped — one repository, one mailbox, one project.
  • Time-limited where supported, so an unnoticed leak expires.

The reasoning is the same as agent permissions: a key that cannot delete cannot be made to delete, whatever instructions the surrounding system is tricked into following. That guarantee comes from the scope, not from careful prompting.

Rate limits

APIs cap how often you may call them. Exceed the cap and you get 429.

Handle it properly:

  1. Read the headers. Most APIs report remaining quota and a reset time. Retry-After tells you exactly how long to wait.
  2. Back off exponentially. Wait 1s, then 2s, then 4s, with a cap. Retrying immediately makes it worse and can escalate to a longer block.
  3. Add jitter. Randomise the delay slightly. Without it, many clients retry in lockstep and re-create the spike.
  4. Give up eventually. After a few attempts, fail honestly rather than retry forever.

Retry 429 and 5xx. Do not retry 4xx — a malformed or unauthorised request will fail identically no matter how many times you send it.

Agents make this sharper

An agent can loop. A loop that hits an error and retries without backoff will exhaust a rate limit in seconds, and a loop that retries a paid endpoint can spend real money quickly.

So: a hard cap on iterations, backoff on every retry, a spend limit if the API is billed per call, and logging of every call so you can reconstruct what happened. These are the same controls as the agent lesson, applied at the integration layer — and they are the difference between an agent that fails safely and one that fails expensively.