API Security & OAuth Security: Protecting Endpoints and Tokens

Most FDE work is building on top of someone else's API — or exposing one. This tutorial covers the two security halves of that: API security (how your own endpoints stay safe: authentication, TLS, rate limits, error hygiene, CORS) and OAuth security (how you obtain and use delegated tokens safely, without falling into the classic OAuth footguns).

Table of Contents

• Two Sides: Your API, Their API
• API Security Fundamentals
• Authenticate Every Request
• Always Over TLS
• Tokens Never in the URL
• Rate Limiting
• Errors Leak Nothing
• CORS: Who May Call From a Browser
• Log for the Incident, Not the Demo
• What OAuth Adds
• OAuth Security Essentials
• Validate redirect_uri, Exactly
• Use PKCE and a state
• Store Tokens the Right Way
• Scope: Least Privilege in Tokens
• The Two Classic OAuth Hacks
• OAuth vs Cookies
• Best Practices

Two Sides: Your API, Their API

As an FDE you almost always work on two sides of an API:

1. Your API — the endpoint you expose to customer tools. The job is defense: reject bad callers cleanly, leak nothing.
2. Their API — the third-party service you call (CRMs, Slack, ERP). The job is credential handling: hold a token safely, use the right scope, never let an OAuth snippet get copied into a log.

This tutorial is both. Everything under API Security protects your endpoint; everything under OAuth Security governs the tokens you handle on either side.

API Security Fundamentals

A well-protected API:

• knows who is calling (auth on every route),
• transports over TLS (no plaintext),
• never puts secrets in URLs (they leak to logs),
• pushes back under abuse (rate limits),
• treats errors as silence (no stack traces to callers),
• and lets browsers call only from origins you allow (CORS).

Each one is a section below.

Authenticate Every Request

Authenticate every request, including the ones that seem harmless. An endpoint that's "just reading" is still an endpoint anyone can quietly mine:

import os, requests

api_key = os.getenv("API_KEY")                     # from the environment (Tutorial 2)
resp = requests.get(
    "https://api.crm.example.com/v1/contacts",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=30,
)
print(resp.status_code)

Explanation: the key travels in the Authorization header — not the URL — and it is read from the environment, not typed into the code. The server authenticates the caller before serving the first row.

Forcing TLS: Route Over TLS

Your API should be reachable only over https://. TLS is what protects your tokens and tokens in transit (Tutorial 4). Don't ship an endpoint that accepts plain http:// "for dev":

• Redirect plain http requests to https.
• Drop support for old, weak cipher-suites where you can.

Note: if a local http:// is genuinely needed for development, bind it to localhost only and document that it never leaves the machine.

Tokens Never in the URL

Query strings survive into logs — access logs, proxies, browser history, analytics. A key in ?key=… is a key that is also in your logs. Put credentials in the Authorization header (or, for a login exchange, in the request body) — never as a URL parameter.

Why this is a hard default: one misplaced key-in-URL ships a credential to every log line the request touches.

Rate Limiting

A public API can be hammered — brute-forcing logins, scraping data, or driving a small customer's quota up. Rate limiting caps how many requests a caller may make in a window, and returns 429 Too Many Requests when the cap is hit (the retry rules live in Integrations Tutorial 3).

Allowed:  100 requests / minute per API key
Over:     429 with Retry-After: 60

Explanation: limit per caller, not globally; return 429 with a retry hint so well-behaved clients back off. This is both a brute-force brake and a DoS shield.

Errors Leak Nothing

An error message is data. A stack trace, a raw SQL error, a DB detail — each reveals the shape of your system. In production, reply to clients with small, safe messages and keep full detail on your side:

try:
    result = run_query(user_input)
except Exception:
    log.exception("query failed")                  # full detail stays yours
    return {"error": "unable to complete request"} # safe message to client

Explanation: the full trace goes to your structured logs; the client gets a generic message that reveals nothing about your stack, DB, or query shape. This starves reconnaissance.

CORS: Who May Call From a Browser

When a browser script calls your API, the browser enforces CORS — a policy that declares which origins may read responses. A server that answers Access-Control-Allow-Origin: * to everything lets any website's JS read your API's responses under the user's cookies or tokens.

• Set Access-Control-Allow-Origin to your real app origins only.
• Avoid blanket * whenever real cookies/tokens are involved.
• CORS is a browser gate only — a non-browser attacker calls your API directly regardless, which is why auth and rate limits stay hard requirements.

Log for the Incident, Not the Demo

Log the audit facts that help you answer a real incident: which authenticated user hit which route, with which identity, timestamped and keyed by request id (Debugging series). When the API is misused, you can reconstruct who and when — not merely "it was called."

Rule of thumb: log user, role, resource, verb, status, and a request id — never passwords, tokens, or full payload bodies.

What OAuth Adds

You met OAuth 2.0 mechanics in Integrations Tutorial 2. Here it's about security alone — the places OAuth goes wrong and how to keep the delegation model safe. The goal is unchanged: the user lets your app act for a while, inside well-defined scopes, without ever giving you their password.

OAuth Security Essentials

Five details carry nearly all the risk. OAuth's power — delegation by token — is also its danger; the whole model stands on how the token is obtained, where it's stored, and what it's scoped to. Get these right and you match the industry default; get one wrong and you become the case study.

Validate redirect_uri, Exactly

In the Authorization Code flow, the provider redirects the user back to your app — with an authorization code — to the redirect_uri you declared when you registered. If the provider doesn't check it exactly, an attacker can supply a different redirect_uri and have the code (and then the token) delivered to their server.

• Send the same redirect_uri you registered.
• The provider must reject any redirect_uri that is not an exact, registered match — an exact string compare against a whitelist.

This is the classic OAuth trap: the safe version refuses mismatches like localhost vs 127.0.0.1, https vs http, or any extra path the attacker appends.

Use PKCE and a state

Two cheap additions plug the biggest browser-flow holes:

• state — a random value you send on the auth request and verify unchanged on return. It blocks CSRF on the callback: an attacker can't force your app to finish a login the victim never started.
• PKCE — a random code_verifier and a hash of it sent as the code_challenge. When you exchange the code, you prove you know the verifier. It stops a stolen code from being replayed by anyone who didn't start the flow.

at the start:  app picks a 'state' and a 'code_verifier'
at the return: app checks 'state' matches, exchanges the code plus the verifier

Do both. PKCE protects the code on the wire; state stops someone from tying the user's session to a login they never started.

Store Tokens the Right Way

The two tokens have very different risk:

The refresh token mints new access tokens, so treat it as a secret: secret-manager or encrypted storage, never in a log, URL, or browser. When the access token expires (a 401), use the refresh flow server-side to mint the next one. Short-lived access plus an armored refresh keeps a leaked token briefly dangerous instead of permanently.

Scope: Least Privilege in Tokens

The scope you request names what your app may do, and you ask for it at the login. Ask for the minimum that works, not a generous "everything." A token scoped read:contacts reads contacts and nothing else:

• request narrowly — read and your needs, not *;
• keep the scope with the token; the API rejects any out-of-scope call;
• revoke scopes you requested but no longer use.

Why it's like least privilege (Tutorial 1): a hijacked narrow token is a bounded leak; a wide "everything" token is a breach in one scoop.

The Two Classic OAuth Hacks

Two incidents define "don't do this":

1. Unvalidated redirect_uri captures a code. An attacker registers, uses an un-accepted redirect_uri, and collects the code meant for the real app. Fix: exact redirect_uri whitelist (see Validate redirect_uri).
2. Long-lived refresh token leaks to a log or URL. A poorly-scoped refresh token sits in a stack trace or ?token=, and is replayed for days to mint new access tokens. Fix: keep refresh tokens in a secret store, bind scopes, never log them.

Both are logic mistakes, not fragile crypto — which is why they return and why the checklist (redirect_uri, state, PKCE, token storage, scopes) matters.

OAuth vs Cookies

Don't confuse the provider's token with your own session cookie. The cookie is the user's session with your app; the OAuth token is how your app proves itself to the provider. And never copy the provider token into a cookie that's sent to every page.

Best Practices

• Authenticate every route, over TLS, credentials in headers — never a URL.
• Rate-limit per identity, returning 429 with Retry-After.
• Errors leak nothing: generic client messages; detail stays your side.
• CORS: whitelist exact origins; a blanket * only when no cookies/tokens are in play.
• Log audit facts (user, role, resource, time) — never tokens or payloads.
• OAuth: exact redirect_uri, a state, PKCE, least scope.
• Keep the access token short-lived and the refresh token guarded as a secret.
• Test the failure paths (token expiry, bad callback, out-of-scope).