> ## Documentation Index
> Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate a session

> How to validate session tokens and JWTs on your backend.

## Use case

* **Protect server-side endpoints:** Validate either the `session_token` or `session_jwt` on requests to your backend before proceeding with the request.
* **Backend authorization checks:** Enforce RBAC permissions and perform server-side user authorization checks before proceeding with the request.

***

## JWT vs. session token validation

Since `session_jwt` and `session_token` are stored in the site's cookies, the browser will include these cookies in the request headers to your backend if they share a domain.

Select between validating a JWT or session token:

> [tab] Validate a JWT
>
> Using JSON Web Tokens (JWT) over opaque session tokens **allows you to validate the token locally entirely within your backend service**, which is significantly faster than communicating with Stytch's API on every user session validation check.
>
> ### Reasons to use JWTs
>
> * **Minimize latency:** JWTs can be locally validated to authenticate sessions without an API call (until it expires).
> * **Authorize actions outside your app:** JWTs contain standard claims and information about the User Session.
>
> ***
>
> ### Using the Stytch SDK
>
> ![JWT validation flow](https://mintcdn.com/stytch-34ca0595/F3sfuxsAeAZ7fNRj/images/sessions/jwt-validation.png?fit=max\&auto=format\&n=F3sfuxsAeAZ7fNRj\&q=85\&s=1b3e63e3b49b68ba4d44f7202d9c41fa)
>
> Session validation using authenticateJwt()
>
> **1. Initialize the SDK**
>
> Upon initialization, the Stytch SDK client will automatically retrieve and cache your JSON Web Key Set (JWKS) for use in local JWT validation.
>
> > [!WARNING]
> >
> > Persist the SDK client instead of reinitializing it between requests so your JWKS is only fetched once.
>
> **2. Validate JWTs using either SDK method**
>
> > [card] [authenticateJwt()](https://stytch.com/docs/api-reference/consumer/api/sessions/authenticate-jwt.md)
> >
> > Handles the local JWT authentication and remote session authentication fallback.
> >
> > **Recommended**
>
> > [card] [authenticate()](https://stytch.com/docs/api-reference/consumer/api/sessions/authenticate-session.md)
> >
> > Always communicates with the Stytch API to authenticate a session.
>
> **3. Using authenticateJwt() example**
>
> ```javascript Node.js icon="node-js" lines theme={null}
> const express = require('express');
> const cookieParser = require('cookie-parser');
>
> const app = express();
> app.use(cookieParser());
> app.use(authenticateStytchSession);
>
> const client = new stytch.Client({
>   project_id: process.env.STYTCH_PROJECT_ID,
>   secret: process.env.STYTCH_SECRET,
> });
>
> const authenticateStytchSession = (req, res, next) => {
> return client.sessions.authenticateJwt({ session_jwt: req.cookies['stytch_session_jwt'] })
>   .then(session => {
>     req.stytchSession = session;
>     return next();
>   })
>   .catch(next)
> };
> ```
>
> **4. Retrieving user data when validating locally**
>
> `authenticateJwt()` does not return the full [User object](https://stytch.com/docs/api-reference/consumer/api/users/user-object.md) when validated locally. If you need data from the User object to complete additional authorization checks or any other additional action, use [custom claims](https://stytch.com/docs/consumer-auth/manage-sessions/custom-claims.md) to add it to the JWT itself.
>
> ***
>
> ### Using custom backend JWT validation
>
> Stytch JWTs are compatible with other standard JWT validation libraries. You'll need to:
>
> * Implement logic to fall back to Stytch's [Authenticate Session](https://stytch.com/docs/api-reference/consumer/api/sessions/authenticate-session.md) endpoint when the JWT is expired. You can refer to the [Authenticate JWT](https://stytch.com/docs/api-reference/consumer/api/sessions/authenticate-jwt.md) method for what that logic might look like.
>
> * Supply your validation library the Stytch [Get JWKS](https://stytch.com/docs/api-reference/consumer/api/sessions/get-jwks.md) endpoint for [JWKS rotation](#json-web-key-set-jwks-rotation). Otherwise, your application should decide which JWKS to use for validation by inspecting the JWT and JWKS `kid` value.
>
> > [accordion] Common libraries
> >
> > * [jose](https://www.npmjs.com/package/jose) (Node.js)
> > * [jwt](https://pkg.go.dev/github.com/golang-jwt/jwt) (Go)
> > * [Hasura](https://hasura.io/docs/2.0/auth/authentication/jwt/)
> > * [NGINX](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-jwt-authentication/)
> > * [Apollo](https://www.apollographql.com/docs/router/configuration/authn-jwt/)
> > * [php-jwt](https://packagist.org/packages/firebase/php-jwt)
>
> > [!NOTE]
> >
> > We strongly recommend using our [backend SDKs](https://stytch.com/docs/api-reference/consumer/api/sdks.md) (available in Python, Node, Ruby, Go, and Java) for JWT validation. Our libraries handle the logic to authenticate JWTs locally and automatically fall back to the Stytch API when the JWT is expired.
>
> ***
>
> ### JSON Web Key Set (JWKS) rotation
>
> Stytch automatically rotates your JWKS every 6 months for security purposes. Newly minted JWTs will be signed using the new key set. **Both key sets** will be returned by the [Get JWKS](https://stytch.com/docs/api-reference/consumer/api/sessions/get-jwks.md) endpoint for a 1 month grace period.
>
> * \~1 month before your Project's old JWKS expires, a new JWKS will be automatically generated.
>
> * When this happens, there will be a 5 minute period where some JWTs will be signed by the old JWKS and some by the new, due to the JWT set lifetime.
>
> * Match the `kid` value of the JWT and JWKS to determine the correct JWKS to use for validation.
>
> * Most JWT libraries have a mechanism to handle this automatically; if not, you may see errors like `"kid" invalid, unable to lookup correct key` (depending on the library and version you use).
>
> > [!TIP]
> >
> > Stytch's [backend SDKs](https://stytch.com/docs/api-reference/consumer/api/sdks.md) handle JWKS rotation for you automatically.

> [tab] Validate a session token
>
> Session tokens are considered opaque because they don't contain any information about the underlying User Session.
>
> ### Reasons to use session tokens
>
> * **Strict security requirements:** Session tokens cannot be locally validated. You must always make a Stytch API call to authenticate the token, which guarantees that the token is valid at that point in time. This provides stricter guarantees than JWTs, which have a 5-minute window where the underlying User Session may have been revoked before the JWT was refreshed.
>
> ***
>
> ### Using the Stytch SDK
>
> **1. Validate a session token using the Authenticate Sessions method**
>
> > [card] [authenticate()](https://stytch.com/docs/api-reference/consumer/api/sessions/authenticate-jwt.md)
> >
> > Always communicates with the Stytch API to authenticate a session.
>
> **2. Using Authenticate Sessions example**
>
> ```python lines theme={null}
> def upgrade_user_to_coordinator():
>   try:
>     resp = client.sessions.authenticate(
>       session_token=session['stytch_session'],
>       custom_claims={
>         "role": "coordinator",
>         "read-scope": ["appointments", "deliveries"],
>         "write-scope": ["calendar"]
>       }
>     )
>     if resp.status != 200:
>       return handle_error(resp.status)
>     session['stytch_session'] = resp.session_token
>     return
>   except Exception as e:
>     return handle_exception(e)
> ```
