Introducing JWTs for session management

We’re excited to launch support for JSON web tokens (JWTs) as part of our session management product! Now, developers can choose between JWTs, session tokens, or a hybrid approach.

Stytch’s JWT support allows you to mint JWTs that can be verified without needing to hit Stytch’s API. This allows for highly performant authorization for your product when you need it, while also providing the control to revoke access when and where you want it. 

JWTs vs session tokens

To authenticate a user, developers can either implement a JWT or session token-based solution. 

A JSON Web Token (or JWT) is an open standard that allows clients and servers to communicate and share critical information. It’s a form of stateless authentication as all user data is stored client-side within the token itself. This makes JWTs a popular session management solution among developers looking to reduce their server load and improve latency — it makes managing sessions faster and scaling architecture easier. JWTs offer numerous benefits, but one downside is that session revocation can be more difficult because the validation happens client-side rather than server-side.

Conversely, session tokens are a session management solution that stores the token on the server-side, along with user data. Session tokens are verified against the server’s database with every user request, and a single token can be easily revoked at any time. This results in higher latency than JWTs. However, when control over session revocation is critical, this solution can be beneficial since it guarantees instant session revocation when needed. 

Get the best of both worlds

Developers often have to decide which session management solution is best to implement and make the tradeoff between security and latency. Here at Stytch, we provide flexibility to strike the right balance for your application. With Stytch session JWTs, the JWT can be validated locally within your app or remotely with the Stytch API. The JWT will expire every 5 minutes in order to ensure that any session revocations are honored in a reasonable time frame, but you will be able to retrieve a new JWT through the Stytch API so long as the underlying session is still valid. You can also customize how frequently you check in with the Stytch servers by setting a lower max_token_age threshold in our client libraries or by triggering a refresh request before allowing particularly sensitive actions.

JWTs for session management are a great solution if:

  • Your performance needs require that your app needs to be able to validate sessions without an external network request on every call.
  • You’re using Stytch session management to authorize actions outside of your app and that authorization works via JWTs.

How Stytch session JWTs works 

Utilize session JWTs exactly the same way as opaque session tokens, by substituting session_token with session_jwt. Every response in our sessions product that contains a session_id and session_token will now also contain a session_jwt. The session_jwt value can be used to attach new factors to existing sessions to enable step up authentication, extend the lifetime of an existing session as well as authenticate and revoke sessions. 

const { session } = await client.sessions.authenticateJwt(session_jwt, {
  max_token_age_seconds: 3600,
});

if (session.authentication_factors.length >= 2) {
  loadSecretData(session.user_id);
} else {
  loadRegularData(session.user_id);
}

A session JWT is a signed snapshot of the session at the time it was issued, and that signature is valid even after the session is revoked in the Stytch API. This means that the JWT is still locally valid even after the session is revoked. In order to ensure that there is a limit to how long a stale JWT could continue to be locally valid despite the underlying session being revoked, the JWT has a 5 minute expiry that is distinct from the configurable session expiry. The Stytch API will return a 404 error if the JWT passed is associated with an invalid session. To authenticate locally, use your client library’s version of authenticate_jwt. 

Stytch will sign all JWTs for your project with project-specific signing keys. The verification keys for those signatures are available at a project-specific URL. The URL is publicly accessible, so any other JWT consumers outside of your app can also use it to verify JWTs from your project. 

What’s next

Here at Stytch, we’re just getting started. We’re looking to add support for custom claims in JWTs and allowing you to store custom user data. Let us know what you’d like to store in your session!

Subscribe to our Changelog to find out about new products we ship and be alerted when we add additional features to existing products. 

Getting started

If you’re interested in using JWTs, check out our Docs and sign up for a developer account here to get started! If you have any questions, please feel free to contact us at support@stytch.com.