session-token Handling
Learn how to handle your session-token and pass it through your system.
When a user logs in into your application, the UI component stores the session-token as a cookie. Since user authentication is determined by the session-token (see Protecting Routes), it must be accessible wherever you need to verify the user’s authentication status.
By default, the Domain
of the session-token cookie is set to the domain the UI component is integrated on (e.g. if the UI component is integrated on https://www.example.com/auth/ the Domain
will be www.example.com).
Thus, there will be different scenarios where the session-token cookie is available and where not:
1) Frontend and backend are on the same domain
This is the simplest scenario. The session-token cookie is available in both the frontend and the backend because they share the same cookie domain.
Frontend
- Frontend runs on https://www.example.com
- User logs in using the Corbado UI component
- The session-token is created and stored as cookie with name
cbo_session_token
andDomain=www.example.com
- User interacts and frontend (JavaScript) sends requests to the backend on https://www.example.com/api
- The session-token cookie is sent with the request to the backend because the
Domain
matches
Backend
- Backend reads session-token from cookie
cbo_session_token
and validates it
2) Frontend and backend are on different domains
In this scenario, the session-token cookie is not available in the backend because the Domain
of the cookie does not match the backend domain (www.example.com
!= api.example.com
).
To make the session-token cookie available in the backend, you have to pass it as bearer token in the Authorization
header.
Frontend
- Frontend runs on https://www.example.com
- User logs in using the Corbado UI component
- The session-token is created and stored as cookie with name
cbo_session_token
andDomain=www.example.com
- User interacts and frontend (JavaScript) sends requests to the backend on https://api.example.com
- The session-token is sent with the request using
Authorization
header (bearer) to the backend because theDomain
does not match
Backend
- Backend reads session-token from
Authorization
header (bearer) and validates it
Since it is technically possible to pass the session-token using other methods like query parameters or other header fields (like X-Session-Token
), we strongly recommend using the Authorization
header. This is the most secure way to pass the session-token.
3) Frontend and multiples backends are on different domains
Scenario 3 is pretty similar to scenario 2. The only difference is that you have multiple backends (like it is common in microservice architectures).
Frontend
- Frontend runs on https://www.example.com
- User logs in using the Corbado UI component
- The session-token is created and stored as cookie with name
cbo_session_token
andDomain=www.example.com
- User interacts and frontend (JavaScript) sends requests to the Shop backend on https://shop.example.com
- The session-token is sent with the request using
Authorization
header (bearer) to the backend because theDomain
does not match
Shop backend
- Shop backend reads session-token from
Authorization
header (bearer) and validates it - Shop backend sends requests to the Payment backend on https://payment.example.com
- The session-token is sent with the request using
Authorization
header (bearer) to the backend because no Browser is involved and we have no cookie handling
Payment backend
- Payment backend reads session-token from
Authorization
header (bearer) and validates it
Since it is technically possible to pass the session-token using other methods like query parameters or other header fields (like X-Session-Token
), we strongly recommend using the Authorization
header. This is the most secure way to pass the session-token.
Was this page helpful?