This is a contributors guide and NOT a user guide. Please visit these docs if you are using or evaluating SuperTokens.

Session verification should check headers then cookies

This is just a proposal so far, it hasn't been accepted and needs further discussion.

Context and Problem Statement#

If the FE sends a request using the wrong authentication method (e.g.: using headers instead of cookies), it could mean:

Depends on default auth mode decision 0003

Example usecases:

Browser w/ SDK
~~Browser w/ old SDK~~ (we require sync update of FE and BE)
~~Browser wo/ SDK~~ (we are not optimizing for this, but basically the same as Postman)
Mobile apps w/ SDK
Mobile apps wo/ SDK
CLI
M2M
~~SSR (same as M2M)~~
~~SSR (same as M2M)~~ w/ ability to read access token on the frontend (for web sockets for example)
Postman (basically CLI w/ cookie storage)
~~Native/desktop apps~~ (same as mobile apps)
~~E2E testing~~ (Same as mobile without SDK)
~~Browser extension w/ SDK~~ (same as browser w/ SDK + some customization)
Migration (from other services using Authorization header with a JWT)

These can be reduced to two things:

Session verification should check headers then cookies:

If idRefreshToken is present, we reject with TRY_REFRESH_TOKEN
Headers is the default method as per this decision
Make sure that updating the access token updates in the fallback case use the same as the incoming request. (e.g: if we read a session from cookies then updateAccessTokenPayload should update the cookies, not headers)

getTokenTransferMethod	sessionRequired	Authorization header	Access token cookie	Output
*	false	none	none	undefined
cookie	false	exists	none	undefined
header	false	none	exists	undefined
*	true	none	none	UNAUTHORISED
cookie	true	exists	none	UNAUTHORISED
header	true	none	exists	UNAUTHORISED
any	*	exists	exist	Based on session validation of header
header	*	exists	exist	Based on session validation of header
cookie	*	exists	exist	Based on session validation of cookie
any	*	exists	none	Based on session validation of header
header	*	exists	none	Based on session validation of header
any	*	none	exists	Based on session validation of cookie
cookie	*	none	exists	Based on session validation of cookie

Also check this decision: Treat Authorization header as empty if it doesn't contain a SuperTokens token
Also check this decision: Optional session verification should throw TRY_REFRESH_TOKEN errors

Easier to communicate - if it doesn't match we reject

Forces the user to sign in again, since refresh won't allow an upgrade (check [here](./0008))

Strictly matches settings

Cookie based requests without our SDKs need to set preference/rid in header, but this is less used