Streambird sessions are identified by session tokens stored on your client’s browser or devices (usually as cookie or in localStorage). This session token will then be sent back to the backend server with every request to identify the user. Streambird returns both a session token and JWT on each successful verification request (e.g. Magic link, OTP, TOTP, etc.). Each session contains information on the user, authentication factors, and device info the user used to log in to your service. The standard session token is a string-based unique token while the session JWT is a JWT token representing that same session encrypted using RS256.

​
Session token

  • Session token is standard unique token that does not contain info on the user or the session it represents.
  • Session token needs to be verified via the Streambird /sessions/verify API on every request before you return success or error to your user.
  • Session token can be revoked easily via /sessions/delete API and hence considered more secure.
Session token has the following benefits and might be preferred in the following scenarios
  • Since session token can be easily revoked, there is no risk of accidentally using an expired token. For example, since session JWT might have a 5 minute expiration time, even if the underlying session is revoked, the JWT might still be considered valid.
  • You prefer an opaque token that does not expose any info of the user or the underlying session in case the token is inspected (for example, user_id and session_id).

​
Session JWT token

  • Streambird session JWTs all contain JWSs (JSON Web Signatures), which are signed using RS256 instead of encrypted (e.g. HS256). A signed JWT can be verified using a public key that is safe to expose, allowing anyone to verify the signed JWT independently.
  • Each JWT has an expiration of 300 seconds (5 minutes), in the exp field of the JWT header. However, you can use the session JWT to get a new session JWT via our /sessions/verify API. You will be able to get a new JWT as long as the underlying session is valid (for example, if your session is 7 days) even JWT token is expired passed the 5 minutes mark. However, if the underlying session has been revoked or expired in the Streambird API, even a valid session JWT will return error in the /sessions/verify API.
  • The JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JSON Web Token (JWT) issued by the Authorization Server and signed using the RS256 signing algorithm.
  • RS256 generates an asymmetric signature, which means a private key must be used to sign the JWT and a different public key must be used to verify the signature.
  • Session JWT contains the full session object, authenticated factors (e.g. OTP, Magic link), and the user ID cryptographically signed.
  • Streambird leverages the JSON Web Key (JWK) spec to represent the cryptographic keys used for signing RS256 tokens.
  • Streambird allows public access of the JWKS endpoint for each app. You can locate the public JWKs at https://api.streambird.io/v1/auth/jwks/{app_id}. Read more about the GetJWKsByApp endpoint.
Session JWT has the following benefits and might be preferred in the following scenarios
  • Session JWT is cryptographically signed and can be verified using the public key in JWKs. You can benefit from performance increase without having to perform an external API call to the /sessions/verify API.
  • Integration with external systems that cannot call the verify session API and rely on JWT standard to verify user sessions of your application.