Authentication

Authentication is proving who's calling — the badge check at the gateway (L236): sessions (the user's logged-in state, L122), tokens (the bearer credential, L240), and API keys (the machine credential, L237) — verified once at the boundary (L236), with the services trusting the gateway's verdict, and the L172 rule holding: the client is never trusted (L172).

The one-sentence interview answer: "Authentication is the badge check — proving who's calling (L237). Three credentials. Sessions — the user's logged-in state (L122): the cookie or the session token, for the human users of the app (L237). Tokens — the bearer credential (L240): a signed token (L240) that says 'this request is from user X, until this time' — for the app's own service calls (L240). API keys — the machine credential (L237): a long-lived secret for the partners' integrations (L237) — the server-to-server identity (L237). The check happens at the gateway (L236): the gateway verifies the credential once, and the services trust it (L236). And the L172 rule holds: the client is never trusted — the badge is verified at the door, not assumed (L237)."

Think of authentication as the three kinds of badges at the front desk. The sessions are the visitor's day pass (the user's logged-in state, L122): it's issued when they sign in and expires when they leave (the session's lifetime, L237). The tokens are the staff ID (the bearer credential, L240): it says who the bearer is and when it expires (L240) — anyone holding it is that person (L240). The API keys are the service badges (the machine credential, L237): long-lived, for the machines that call each other (L237). The front desk (the gateway, L236) checks whichever badge the visitor presents (L237) — and the offices (the services) trust the front desk's check (L236).

   the three badges (L237)
   ┌────────────────────────────────────────────────────────┐
   │ session  — the day pass (L122) — the user's login      │
   │ token    — the staff ID (L240) — who holds it is who   │
   │ key      — the service badge (L237) — the machine      │
   └────────────────────────────────────────────────────────┘
       checked at the front desk (L236), trusted by the offices (L236)

The mental model is the three badges: the session, the token, and the key — each checked at the front desk (L237).

   a request arrives (L237)
        │
        ▼
   ┌──────────────────────────────────────────────────────────┐
   │ 1 · PRESENT THE CREDENTIAL (L237)                        │
   │     the session cookie · the bearer token (L240) ·       │
   │     the API key (L237)                                   │
   └──────────────────┬───────────────────────────────────────┘
                      ▼
   ┌──────────────────────────────────────────────────────────┐
   │ 2 · VERIFY (L237)                                        │
   │     the session: valid? not expired? (L122)              │
   │     the token: signature? expiry? (L240)                 │
   │     the key: known? scoped? (L237)                       │
   └──────────────────┬───────────────────────────────────────┘
                      ▼
   ┌──────────────────────────────────────────────────────────┐
   │ 3 · THE VERDICT (L236)                                   │
   │     valid → the session is set (L237)                    │
   │     invalid → 401 (L234)                                 │
   └──────────────────┬───────────────────────────────────────┘
                      ▼
   the services trust the verdict (L236) — the request proceeds (L233)

The flow is the badge check: present → verify → verdict → trusted (L237).

• Sessions (L122). The user's logged-in state (L122): the login issues a session (L237), the session travels with the requests (the cookie, L237), and the server looks it up (L237). The session is the human user's badge (L237).
• Tokens (L240). The bearer credential (L240): a signed token (L240) carrying the user's identity and the expiry (L240). The bearer — whoever holds it — is that identity (L240). The token is verified by its signature (L240).
• API keys (L237). The machine credential (L237): a long-lived secret for the partners and the integrations (L237) — the server-to-server identity (L237). The key is hashed at rest (L275) and scoped (L315).
• The boundary (L236). The verification happens at the gateway (L236): the credential is checked once (L237), and the services trust the gateway's verdict (L236) — the services never re-implement auth (L236).

• The web app (L122). The users sign in → the session (L122) → the chat requests authenticated at the gateway (L236).
• The mobile app (L240). The users sign in → the token (L240) → the bearer credential on the requests (L240).
• The partner API (L237). The partners' integrations → the API keys (L237) → scoped per partner (L315).
• The service-to-service calls (L240). The app's own services → the service tokens (L240) with the short expiry (L240).
• The AI SaaS (L260). The three audiences (L237) authenticated at the gateway (L236) — the users, the services, the partners (L260).

The through-line: the credential matches the caller — the session for the humans, the token for the services, the key for the machines — verified at the door (L237).

Say it in four moves:

1. The three credentials. "Sessions (L122), tokens (L240), keys (L237)."
2. The match. "The session for the users, the token for the services, the key for the machines (L237)."
3. The boundary. "Verified at the gateway (L236) — the services trust it (L236)."
4. The rule. "The client is never trusted — the badge is checked at the door (L172)."

• The credential matches the audience (L237). The senior answer designs the auth per caller (L237): the users' sessions (L122), the services' tokens (L240), the partners' keys (L237) — each with its own lifetime and revocation (L237).
• The token is verified by its signature (L240). The bearer credential (L240) — the signature (L240) and the expiry (L240) verified, not the database (L240).
• The keys are hashed and scoped (L275, L315). The API keys hashed at rest (L275) and scoped per partner (L315) — the machine credential's hygiene (L237).
• The boundary is the gateway (L236). Auth verified once at the door (L236) — the services never re-implement it (L237).
• The revocation is the lifecycle (L237). The sessions revocable (L122), the tokens short-lived (L240), the keys rotatable (L275) — the credential's lifecycle is the auth's design (L237).

• Trusting the client (L172). The app's identity assumed (L172) — the badge not checked (L237).
• The wrong credential (L237). The API key for the human users (L237) — the session (L122) or the token (L240) is the fit (L237).
• The token unverified (L240). The bearer accepted without the signature (L240) — the forgery (L240).
• The keys in the client (L275). The machine credential exposed (L172) — the server-side rule (L275) broken.
• Auth per service (L236). Each service re-implementing the check (L236) — the scattered drift (L172).
• No revocation (L237). The long-lived credentials never rotatable (L275) — the leaked badge lives forever (L237).

• Match the credential to the caller (L237) — the session (L122), the token (L240), the key (L237).
• Verify at the gateway (L236) — the services trust the verdict (L237).
• Verify the token's signature (L240) — and the expiry (L240).
• Hash and scope the keys (L275, L315) — the machine credential's hygiene (L237).
• Design the revocation (L237) — the sessions revocable (L122), the keys rotatable (L275).
• Never trust the client (L172) — the badge checked at the door (L236).

Q: How do you authenticate an AI API?

A: The badge check at the gateway (L236). Three credentials, matched to the caller (L237): the session (L122) for the human users — the logged-in state; the token (L240) for the app's service calls — the bearer credential; and the API key (L237) for the partners' integrations — the machine credential. The gateway (L236) verifies once, and the services trust it (L236).

Q: What's the difference between a session and a token?

A: The state and the verification (L237). The session (L122) is the server-held state: the login issues it, the request carries the cookie, and the server looks it up (L237). The token (L240) is the self-contained bearer credential: it carries the identity and the expiry (L240), verified by its signature (L240) — no server lookup. The session for the interactive users (L122), the token for the service calls (L240).

Q: When do you use API keys?

A: For the machines (L237). The partners' integrations, the server-to-server calls (L237) — a long-lived secret that identifies the caller (L237). The key is hashed at rest (L275), scoped per partner (L315), and rotatable (L275). For the human users, the session (L122) or the token (L240) is the fit — the key is the machine's badge (L237).

Q: Why authenticate at the gateway?

A: Because the gateway is the boundary (L236). Every request passes through it (L233), so the badge is checked once (L236) — and the services trust the verdict (L236). Scattered auth drifts and gets skipped (L172). The gateway is where the L172 discipline — never trust the client — is enforced (L236).

• What are the three credentials (L237)?
• Session vs token (L237)?
• When are API keys right (L237)?
• Why verify at the gateway (L236)?
• What's the revocation story (L237)?

The senior read: the caller column is the choice — the credential matches the audience (L237).

// Authentication at the gateway: the three credentials (L237, L236).
export async function authenticate(req) {
  const auth = req.headers.authorization;

  // 1 · THE SESSION (L122) — the human user's day pass.
  if (req.cookies?.session) {
    const session = await sessionStore.get(req.cookies.session);   // the lookup (L237)
    if (session && !session.expired) return { kind: 'session', user: session.user };
  }

  // 2 · THE TOKEN (L240) — the staff ID, verified by the signature (L240).
  if (auth?.startsWith('Bearer ')) {
    const payload = verifyJwt(auth.slice(7));          // the signature + expiry (L240)
    if (payload) return { kind: 'token', user: payload.sub, scopes: payload.scopes };
  }

  // 3 · THE API KEY (L237) — the service badge, hashed and scoped (L275, L315).
  if (auth?.startsWith('Key ')) {
    const key = await keyStore.find(hash(auth.slice(4)));   // the hash lookup (L275)
    if (key && !key.revoked) return { kind: 'key', tenant: key.tenant, scopes: key.scopes };
  }

  return null;                                         // 401 — no badge (L234)
}

// THE GATEWAY (L236) — the verdict, trusted by the services (L236).
const session = await authenticate(req);
if (!session) return error(401, 'unauthenticated');    // the badge check (L237)

What the reader must SEE — the three badges, one door:

  sessionStore.get()  → the day pass (L122, L237)
  verifyJwt()         → the staff ID's signature (L240)
  keyStore.find(hash) → the service badge, hashed (L275, L315)
  return null → 401   → the badge check (L234)

  The credential matches the caller — verified at the door (L237).

• The session lookup is the fast path (L151). The session store in Redis (L243) — the lookup sub-millisecond (L237).
• The token verification is stateless (L151). The signature (L240) — no lookup, the fastest path (L240).
• The key hash is the lookup cost (L151). The hashed key (L275) in Redis (L243) — the machine credential's check (L237).
• The gateway is the latency budget (L151). The auth (L237) is the first check — kept fast (L236).

• Authentication = the badge check (L237) — proving who's calling.
• The three credentials: session (L122), token (L240), key (L237).
• The match: the user → session, the service → token, the machine → key (L237).
• The boundary: verified at the gateway (L236), trusted by the services.
• The rule: the client is never trusted (L172).
• The lifecycle: revocable sessions (L122), expiring tokens (L240), rotatable keys (L275).

AUTHENTICATION = the badge check at the gateway

THE THREE CREDENTIALS (L237)
  session  the human user's day pass (L122) — the logged-in state
           the server-held lookup (L237) · revocable (L122)
  token    the staff ID (L240) — the bearer credential
           self-contained: the identity + the expiry (L240)
           verified by the signature (L240)
  key      the service badge (L237) — the machine credential
           hashed at rest (L275) · scoped (L315) · rotatable (L275)

THE MATCH (L237)
  the user → the session (L122) · the service → the token (L240)
  the machine → the key (L237) — the credential fits the caller

THE BOUNDARY (L236)
  verified once at the gateway (L236) — the services trust it (L236)
  the client is never trusted (L172) — the badge checked at the door

THE LIFECYCLE (L237)
  sessions revocable (L122) · tokens expiring (L240)
  keys rotatable (L275) — the credential's life is the design

INTERVIEW, 4 MOVES
  1 three   "session, token, key (L237)"
  2 match   "the caller picks the credential (L237)"
  3 boundary "verified at the gateway (L236), trusted by the services"
  4 rule    "the client is never trusted (L172)"

You now hold the badge check: the session for the users, the token for the services, the key for the machines — each verified at the gateway, each with its lifecycle. The front door now knows who's calling (L237).

Next: what they're allowed to do — authorization (L238), scopes, quotas, and policy.