Update: Authentication Cheat Sheet – API-based authentication flow reference

[Alvi24-hub]

What is missing or needs to be updated?

The Authentication Cheat Sheet provides detailed guidance on individual mechanisms (sessions, reauthentication, MFA, token handling), but it does not clearly describe where authentication and authorization decisions should occur in a modern API-based architecture.

For developers building API-first systems (e.g., REST APIs, FastAPI/Django APIs, microservices), it is often unclear which responsibilities belong to:

• login endpoints,
• middleware,
• token refresh endpoints,
• or mid-session risk escalation logic.

This lack of architectural context can lead to inconsistent or insecure implementations, even when individual recommendations are followed.

How should this be resolved?

Add a short, diagram-style documentation subsection to the Authentication Cheat Sheet titled:

“Where authentication decisions should occur in an API-based system”

The subsection would:

• Describe the request lifecycle in an API-driven architecture
• Explain the responsibilities of:
  • Login endpoints
  • Authentication/authorization middleware
  • Token refresh endpoints
  • Mid-session reauthentication or risk escalation
• Be framework-agnostic and text-based (no images required)
• Reference existing sections such as Session Management and Reauthentication After Risk Events

This addition would connect existing guidance into a practical architectural model without changing any existing recommendations.

[Alvi24-hub]

Hi, I’d like to work on this issue. Please assign it to me.

[jmanico]

Please focus on several small pr's as opposed to one giant one so we can triage best.

[Alvi24-hub]

Thanks for the guidance! I’ll split this into several small PRs and start with the first focused update.

[mackowski]

this duplicates other cheatsheets. btw @dadrus when we can release you work from https://github.com/OWASP/CheatSheetSeries/tree/master/cheatsheets_draft ;-)

[dadrus]

@mackowski Hi and please excuse the silence. Actually, and I’m really sorry for the delay, I wanted to finalize the remaining parts at the end of December last year. We are now at the end of March, and I’ve still not finished it.

There is, however, some light at the end of the tunnel. I’ll get some time after Easter and will at least finish the next two sheets. After that, only the core concepts and the recommendation part will remain, which will hopefully make up the last cheat sheet.

@AlexB1986 and I wanted to do that last part together. Hopefully he’ll be available then.