stytch 6.4.0 → 7.2.0

data/lib/stytch/otps.rb

@@ -101,6 +101,7 @@ module Stytch
       session_jwt: nil,
       session_custom_claims: nil
     )
+      headers = {}
       request = {
         method_id: method_id,
         code: code
@@ -112,7 +113,7 @@ module Stytch
       request[:session_jwt] = session_jwt unless session_jwt.nil?
       request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
 
-      post_request('/v1/otps/authenticate', request)
+      post_request('/v1/otps/authenticate', request, headers)
     end
 
     class Sms
@@ -129,11 +130,13 @@ module Stytch
       # ### Cost to send SMS OTP
       # Before configuring SMS or WhatsApp OTPs, please review how Stytch [bills the costs of international OTPs](https://stytch.com/pricing) and understand how to protect your app against [toll fraud](https://stytch.com/docs/guides/passcodes/toll-fraud/overview).
       #
-      # ### Add a phone number to an existing user
+      # __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS prior to October 2023. If you're interested in sending international SMS, please reach out to [support@stytch.com](mailto:support@stytch.com?subject=Enable%20international%20SMS).
+      #
+      # Even when international SMS is enabled, we do not support sending SMS to countries on our [Unsupported countries list](https://stytch.com/docs/guides/passcodes/unsupported-countries).
       #
-      # This endpoint also allows you to add a new phone number to an existing Stytch User. Including a `user_id`, `session_token`, or `session_jwt` in the request will add the phone number to the pre-existing Stytch User upon successful authentication.
+      # ### Add a phone number to an existing user
       #
-      # Adding a new phone number to an existing Stytch User requires the user to be present and validate the phone number via OTP. This requirement is in place to prevent account takeover attacks.
+      # This endpoint also allows you to add a new phone number to an existing Stytch User. Including a `user_id`, `session_token`, or `session_jwt` in your Send one-time passcode by SMS request will add the new, unverified phone number to the existing Stytch User. If the user successfully authenticates within 5 minutes, the new phone number will be marked as verified and remain permanently on the existing Stytch User. Otherwise, it will be removed from the User object, and any subsequent login requests using that phone number will create a new User.
       #
       # ### Next steps
       #
@@ -190,6 +193,7 @@ module Stytch
         session_token: nil,
         session_jwt: nil
       )
+        headers = {}
         request = {
           phone_number: phone_number
         }
@@ -200,13 +204,18 @@ module Stytch
         request[:session_token] = session_token unless session_token.nil?
         request[:session_jwt] = session_jwt unless session_jwt.nil?
 
-        post_request('/v1/otps/sms/send', request)
+        post_request('/v1/otps/sms/send', request, headers)
       end
 
       # Send a One-Time Passcode (OTP) to a User using their phone number. If the phone number is not associated with a user already, a user will be created.
       #
       # ### Cost to send SMS OTP
       # Before configuring SMS or WhatsApp OTPs, please review how Stytch [bills the costs of international OTPs](https://stytch.com/pricing) and understand how to protect your app against [toll fraud](https://stytch.com/docs/guides/passcodes/toll-fraud/overview).
+      #
+      # __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS prior to October 2023. If you're interested in sending international SMS, please reach out to [support@stytch.com](mailto:support@stytch.com?subject=Enable%20international%20SMS).
+      #
+      # Even when international SMS is enabled, we do not support sending SMS to countries on our [Unsupported countries list](https://stytch.com/docs/guides/passcodes/unsupported-countries).
+      #
       # ### Next steps
       #
       # Collect the OTP which was delivered to the User. Call [Authenticate OTP](https://stytch.com/docs/api/authenticate-otp) using the OTP `code` along with the `phone_id` found in the response as the `method_id`.
@@ -261,6 +270,7 @@ module Stytch
         create_user_as_pending: nil,
         locale: nil
       )
+        headers = {}
         request = {
           phone_number: phone_number
         }
@@ -269,7 +279,7 @@ module Stytch
         request[:create_user_as_pending] = create_user_as_pending unless create_user_as_pending.nil?
         request[:locale] = locale unless locale.nil?
 
-        post_request('/v1/otps/sms/login_or_create', request)
+        post_request('/v1/otps/sms/login_or_create', request, headers)
       end
     end
 
@@ -289,9 +299,7 @@ module Stytch
       #
       # ### Add a phone number to an existing user
       #
-      # This endpoint also allows you to add a new phone number to an existing Stytch User. Including a `user_id`, `session_token`, or `session_jwt` in the request will add the phone number to the pre-existing Stytch User upon successful authentication.
-      #
-      # Adding a new phone number to an existing Stytch User requires the user to be present and validate the phone number via OTP. This requirement is in place to prevent account takeover attacks.
+      # This endpoint also allows you to add a new phone number to an existing Stytch User. Including a `user_id`, `session_token`, or `session_jwt` in your Send one-time passcode by WhatsApp request will add the new, unverified phone number to the existing Stytch User. If the user successfully authenticates within 5 minutes, the new phone number will be marked as verified and remain permanently on the existing Stytch User. Otherwise, it will be removed from the User object, and any subsequent login requests using that phone number will create a new User.
       #
       # ### Next steps
       #
@@ -348,6 +356,7 @@ module Stytch
         session_token: nil,
         session_jwt: nil
       )
+        headers = {}
         request = {
           phone_number: phone_number
         }
@@ -358,7 +367,7 @@ module Stytch
         request[:session_token] = session_token unless session_token.nil?
         request[:session_jwt] = session_jwt unless session_jwt.nil?
 
-        post_request('/v1/otps/whatsapp/send', request)
+        post_request('/v1/otps/whatsapp/send', request, headers)
       end
 
       # Send a one-time passcode (OTP) to a User's WhatsApp using their phone number. If the phone number is not associated with a User already, a User will be created.
@@ -420,6 +429,7 @@ module Stytch
         create_user_as_pending: nil,
         locale: nil
       )
+        headers = {}
         request = {
           phone_number: phone_number
         }
@@ -428,7 +438,7 @@ module Stytch
         request[:create_user_as_pending] = create_user_as_pending unless create_user_as_pending.nil?
         request[:locale] = locale unless locale.nil?
 
-        post_request('/v1/otps/whatsapp/login_or_create', request)
+        post_request('/v1/otps/whatsapp/login_or_create', request, headers)
       end
     end
 
@@ -442,9 +452,7 @@ module Stytch
       # Send a One-Time Passcode (OTP) to a User using their email. If you'd like to create a user and send them a passcode with one request, use our [log in or create endpoint](https://stytch.com/docs/api/log-in-or-create-user-by-email-otp).
       #
       # ### Add an email to an existing user
-      # This endpoint also allows you to add a new email to an existing Stytch User. Including a `user_id`, `session_token`, or `session_jwt` in the request will add the email to the pre-existing Stytch User upon successful authentication.
-      #
-      # Adding a new email to an existing Stytch User requires the User to be present and validate the email via OTP. This requirement is in place to prevent account takeover attacks.
+      # This endpoint also allows you to add a new email address to an existing Stytch User. Including a `user_id`, `session_token`, or `session_jwt` in your Send one-time passcode by email request will add the new, unverified email address to the existing Stytch User. If the user successfully authenticates within 5 minutes, the new email address will be marked as verified and remain permanently on the existing Stytch User. Otherwise, it will be removed from the User object, and any subsequent login requests using that email address will create a new User.
       #
       # ### Next steps
       # Collect the OTP which was delivered to the user. Call [Authenticate OTP](https://stytch.com/docs/api/authenticate-otp) using the OTP `code` along with the `phone_id` found in the response as the `method_id`.
@@ -508,6 +516,7 @@ module Stytch
         login_template_id: nil,
         signup_template_id: nil
       )
+        headers = {}
         request = {
           email: email
         }
@@ -520,7 +529,7 @@ module Stytch
         request[:login_template_id] = login_template_id unless login_template_id.nil?
         request[:signup_template_id] = signup_template_id unless signup_template_id.nil?
 
-        post_request('/v1/otps/email/send', request)
+        post_request('/v1/otps/email/send', request, headers)
       end
 
       # Send a one-time passcode (OTP) to a User using their email. If the email is not associated with a User already, a User will be created.
@@ -587,6 +596,7 @@ module Stytch
         login_template_id: nil,
         signup_template_id: nil
       )
+        headers = {}
         request = {
           email: email
         }
@@ -597,7 +607,7 @@ module Stytch
         request[:login_template_id] = login_template_id unless login_template_id.nil?
         request[:signup_template_id] = signup_template_id unless signup_template_id.nil?
 
-        post_request('/v1/otps/email/login_or_create', request)
+        post_request('/v1/otps/email/login_or_create', request, headers)
       end
     end
   end

data/lib/stytch/passwords.rb

@@ -100,6 +100,7 @@ module Stytch
       untrusted_metadata: nil,
       name: nil
     )
+      headers = {}
       request = {
         email: email,
         password: password
@@ -110,7 +111,7 @@ module Stytch
       request[:untrusted_metadata] = untrusted_metadata unless untrusted_metadata.nil?
       request[:name] = name unless name.nil?
 
-      post_request('/v1/passwords', request)
+      post_request('/v1/passwords', request, headers)
     end
 
     # Authenticate a user with their email address and password. This endpoint verifies that the user has a password currently set, and that the entered password is correct. There are two instances where the endpoint will return a `reset_password` error even if they enter their previous password:
@@ -185,6 +186,7 @@ module Stytch
       session_jwt: nil,
       session_custom_claims: nil
     )
+      headers = {}
       request = {
         email: email,
         password: password
@@ -194,7 +196,7 @@ module Stytch
       request[:session_jwt] = session_jwt unless session_jwt.nil?
       request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
 
-      post_request('/v1/passwords/authenticate', request)
+      post_request('/v1/passwords/authenticate', request, headers)
     end
 
     # This API allows you to check whether or not the user’s provided password is valid, and to provide feedback to the user on how to increase the strength of their password.
@@ -248,12 +250,13 @@ module Stytch
       password:,
       email: nil
     )
+      headers = {}
       request = {
         password: password
       }
       request[:email] = email unless email.nil?
 
-      post_request('/v1/passwords/strength_check', request)
+      post_request('/v1/passwords/strength_check', request, headers)
     end
 
     # Adds an existing password to a User's email that doesn't have a password yet. We support migrating users from passwords stored with `bcrypt`, `scrypt`, `argon2`, `MD-5`, `SHA-1`, or `PBKDF2`. This endpoint has a rate limit of 100 requests per second.
@@ -289,6 +292,11 @@ module Stytch
     # untrusted_metadata::
     #   The `untrusted_metadata` field contains an arbitrary JSON object of application-specific data. Untrusted metadata can be edited by end users directly via the SDK, and **cannot be used to store critical information.** See the [Metadata](https://stytch.com/docs/api/metadata) reference for complete field behavior details.
     #   The type of this field is nilable +object+.
+    # set_email_verified::
+    #   Whether to set the user's email as verified. This is a dangerous field. Incorrect use may lead to users getting erroneously
+    #                 deduplicated into one user object. This flag should only be set if you can attest that the user owns the email address in question.
+    #                 Access to this field is restricted. To enable it, please send us a note at support@stytch.com.
+    #   The type of this field is nilable +Boolean+.
     # name::
     #   The name of the user. Each field in the name object is optional.
     #   The type of this field is nilable +Name+ (+object+).
@@ -324,8 +332,10 @@ module Stytch
       pbkdf_2_config: nil,
       trusted_metadata: nil,
       untrusted_metadata: nil,
+      set_email_verified: nil,
       name: nil
     )
+      headers = {}
       request = {
         email: email,
         hash: hash,
@@ -338,9 +348,10 @@ module Stytch
       request[:pbkdf_2_config] = pbkdf_2_config unless pbkdf_2_config.nil?
       request[:trusted_metadata] = trusted_metadata unless trusted_metadata.nil?
       request[:untrusted_metadata] = untrusted_metadata unless untrusted_metadata.nil?
+      request[:set_email_verified] = set_email_verified unless set_email_verified.nil?
       request[:name] = name unless name.nil?
 
-      post_request('/v1/passwords/migrate', request)
+      post_request('/v1/passwords/migrate', request, headers)
     end
 
     class Email
@@ -415,30 +426,34 @@ module Stytch
         locale: nil,
         reset_password_template_id: nil
       )
+        headers = {}
         request = {
           email: email
         }
         request[:reset_password_redirect_url] = reset_password_redirect_url unless reset_password_redirect_url.nil?
-        unless reset_password_expiration_minutes.nil?
-          request[:reset_password_expiration_minutes] =
-            reset_password_expiration_minutes
-        end
+        request[:reset_password_expiration_minutes] = reset_password_expiration_minutes unless reset_password_expiration_minutes.nil?
         request[:code_challenge] = code_challenge unless code_challenge.nil?
         request[:attributes] = attributes unless attributes.nil?
         request[:login_redirect_url] = login_redirect_url unless login_redirect_url.nil?
         request[:locale] = locale unless locale.nil?
         request[:reset_password_template_id] = reset_password_template_id unless reset_password_template_id.nil?
 
-        post_request('/v1/passwords/email/reset/start', request)
+        post_request('/v1/passwords/email/reset/start', request, headers)
       end
 
       # Reset the user’s password and authenticate them. This endpoint checks that the magic link `token` is valid, hasn’t expired, or already been used – and can optionally require additional security settings, such as the IP address and user agent matching the initial reset request.
       #
       # The provided password needs to meet our password strength requirements, which can be checked in advance with the password strength endpoint. If the token and password are accepted, the password is securely stored for future authentication and the user is authenticated.
       #
+      # Note that a successful password reset by email will revoke all active sessions for the `user_id`.
+      #
       # == Parameters:
       # token::
-      #   The token to authenticate.
+      #   The Passwords `token` from the `?token=` query parameter in the URL.
+      #
+      #       In the redirect URL, the `stytch_token_type` will be `login` or `reset_password`.
+      #
+      #       See examples and read more about redirect URLs [here](https://stytch.com/docs/guides/dashboard/redirect-urls).
       #   The type of this field is +String+.
       # password::
       #   The password of the user
@@ -512,6 +527,7 @@ module Stytch
         attributes: nil,
         options: nil
       )
+        headers = {}
         request = {
           token: token,
           password: password
@@ -524,7 +540,7 @@ module Stytch
         request[:attributes] = attributes unless attributes.nil?
         request[:options] = options unless options.nil?
 
-        post_request('/v1/passwords/email/reset', request)
+        post_request('/v1/passwords/email/reset', request, headers)
       end
     end
 
@@ -537,6 +553,8 @@ module Stytch
 
       # Reset the User’s password using their existing password.
       #
+      # Note that a successful password reset via an existing password will revoke all active sessions for the `user_id`.
+      #
       # == Parameters:
       # email::
       #   The email address of the end user.
@@ -605,6 +623,7 @@ module Stytch
         session_jwt: nil,
         session_custom_claims: nil
       )
+        headers = {}
         request = {
           email: email,
           existing_password: existing_password,
@@ -615,7 +634,7 @@ module Stytch
         request[:session_jwt] = session_jwt unless session_jwt.nil?
         request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
 
-        post_request('/v1/passwords/existing_password/reset', request)
+        post_request('/v1/passwords/existing_password/reset', request, headers)
       end
     end
 
@@ -628,6 +647,8 @@ module Stytch
 
       # Reset the user’s password using their existing session. The endpoint will error if the session does not have a password, email magic link, or email OTP authentication factor that has been issued within the last 5 minutes. This endpoint requires either a `session_jwt` or `session_token` be included in the request.
       #
+      # Note that a successful password reset via an existing session will revoke all active sessions for the `user_id`, except for the one used during the reset flow.
+      #
       # == Parameters:
       # password::
       #   The password of the user
@@ -638,6 +659,22 @@ module Stytch
       # session_jwt::
       #   The `session_jwt` associated with a User's existing Session.
       #   The type of this field is nilable +String+.
+      # session_duration_minutes::
+      #   Set the session lifetime to be this many minutes from now. This will start a new session if one doesn't already exist,
+      #   returning both an opaque `session_token` and `session_jwt` for this session. Remember that the `session_jwt` will have a fixed lifetime of
+      #   five minutes regardless of the underlying session duration, and will need to be refreshed over time.
+      #
+      #   This value must be a minimum of 5 and a maximum of 527040 minutes (366 days).
+      #
+      #   If a `session_token` or `session_jwt` is provided then a successful authentication will continue to extend the session this many minutes.
+      #
+      #   If the `session_duration_minutes` parameter is not specified, a Stytch session will not be created.
+      #   The type of this field is nilable +Integer+.
+      # session_custom_claims::
+      #   Add a custom claims map to the Session being authenticated. Claims are only created if a Session is initialized by providing a value in `session_duration_minutes`. Claims will be included on the Session object and in the JWT. To update a key in an existing Session, supply a new value. To delete a key, supply a null value.
+      #
+      #   Custom claims made with reserved claims ("iss", "sub", "aud", "exp", "nbf", "iat", "jti") will be ignored. Total custom claims size cannot exceed four kilobytes.
+      #   The type of this field is nilable +object+.
       #
       # == Returns:
       # An object with the following fields:
@@ -650,6 +687,12 @@ module Stytch
       # user::
       #   The `user` object affected by this API call. See the [Get user endpoint](https://stytch.com/docs/api/get-user) for complete response field details.
       #   The type of this field is +User+ (+object+).
+      # session_token::
+      #   A secret token for a given Stytch Session.
+      #   The type of this field is +String+.
+      # session_jwt::
+      #   The JSON Web Token (JWT) for a given Stytch Session.
+      #   The type of this field is +String+.
       # status_code::
       #   The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
       #   The type of this field is +Integer+.
@@ -662,15 +705,20 @@ module Stytch
       def reset(
         password:,
         session_token: nil,
-        session_jwt: nil
+        session_jwt: nil,
+        session_duration_minutes: nil,
+        session_custom_claims: nil
       )
+        headers = {}
         request = {
           password: password
         }
         request[:session_token] = session_token unless session_token.nil?
         request[:session_jwt] = session_jwt unless session_jwt.nil?
+        request[:session_duration_minutes] = session_duration_minutes unless session_duration_minutes.nil?
+        request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
 
-        post_request('/v1/passwords/session/reset', request)
+        post_request('/v1/passwords/session/reset', request, headers)
       end
     end
   end

data/lib/stytch/rbac_local.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'request_helper'
+
+module StytchB2B
+  class PolicyCache
+    def initialize(rbac_client:)
+      @rbac_client = rbac_client
+      @policy_last_update = 0
+      @cached_policy = nil
+    end
+
+    def reload_policy
+      @cached_policy = @rbac_client.policy['policy']
+      @policy_last_update = Time.now.to_i
+    end
+
+    def get_policy(invalidate: false)
+      reload_policy if invalidate || @cached_policy.nil? || @policy_last_update < Time.now.to_i - 300
+      @cached_policy
+    end
+
+    # Performs an authorization check against the project's policy and a set of roles. If the
+    # check succeeds, this method will return. If the check fails, a PermissionError
+    # will be raised. It's also possible for a TenancyError to be raised if the
+    # subject_org_id does not match the authZ request organization_id.
+    # authorization_check is an object with keys 'action', 'resource_id', and 'organization_id'
+    def perform_authorization_check(
+      subject_roles:,
+      subject_org_id:,
+      authorization_check:
+    )
+      request_org_id = authorization_check['organization_id']
+      raise Stytch::TenancyError.new(subject_org_id, request_org_id) if request_org_id != subject_org_id
+
+      policy = get_policy
+
+      for role in policy['roles']
+        next unless subject_roles.include?(role['role_id'])
+
+        for permission in role['permissions']
+          actions = permission['actions']
+          resource = permission['resource_id']
+          has_matching_action = actions.include?('*') || actions.include?(authorization_check['action'])
+          has_matching_resource = resource == authorization_check['resource_id']
+          if has_matching_action && has_matching_resource
+            # All good
+            return
+          end
+        end
+      end
+
+      # If we get here, we didn't find a matching permission
+      raise Stytch::PermissionError, authorization_check
+    end
+  end
+end

data/lib/stytch/request_helper.rb

@@ -2,29 +2,33 @@
 
 module Stytch
   module RequestHelper
-    def get_request(path)
+    def get_request(path, headers)
       @connection.get(
-        path
+        path,
+        headers
       ).body
     end
 
-    def post_request(path, payload)
+    def post_request(path, payload, headers)
       @connection.post(
         path,
-        payload
+        payload,
+        headers
       ).body
     end
 
-    def put_request(path, payload)
+    def put_request(path, payload, headers)
       @connection.put(
         path,
-        payload
+        payload,
+        headers
       ).body
     end
 
-    def delete_request(path)
+    def delete_request(path, headers)
       @connection.delete(
-        path
+        path,
+        headers
       ).body
     end
 

data/lib/stytch/sessions.rb

@@ -54,11 +54,12 @@ module Stytch
     def get(
       user_id:
     )
+      headers = {}
       query_params = {
         user_id: user_id
       }
       request = request_with_query_params('/v1/sessions', query_params)
-      get_request(request)
+      get_request(request, headers)
     end
 
     # Authenticate a session token and retrieve associated session data. If `session_duration_minutes` is included, update the lifetime of the session to be that many minutes from now. All timestamps are formatted according to the RFC 3339 standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`. This endpoint requires exactly one `session_jwt` or `session_token` as part of the request. If both are included you will receive a `too_many_session_arguments` error.
@@ -108,13 +109,14 @@ module Stytch
       session_jwt: nil,
       session_custom_claims: nil
     )
+      headers = {}
       request = {}
       request[:session_token] = session_token unless session_token.nil?
       request[:session_duration_minutes] = session_duration_minutes unless session_duration_minutes.nil?
       request[:session_jwt] = session_jwt unless session_jwt.nil?
       request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
 
-      post_request('/v1/sessions/authenticate', request)
+      post_request('/v1/sessions/authenticate', request, headers)
     end
 
     # Revoke a Session, immediately invalidating all of its session tokens. You can revoke a session in three ways: using its ID, or using one of its session tokens, or one of its JWTs. This endpoint requires exactly one of those to be included in the request. It will return an error if multiple are present.
@@ -143,15 +145,24 @@ module Stytch
       session_token: nil,
       session_jwt: nil
     )
+      headers = {}
       request = {}
       request[:session_id] = session_id unless session_id.nil?
       request[:session_token] = session_token unless session_token.nil?
       request[:session_jwt] = session_jwt unless session_jwt.nil?
 
-      post_request('/v1/sessions/revoke', request)
+      post_request('/v1/sessions/revoke', request, headers)
     end
 
-    # Get the JSON Web Key Set (JWKS) for a Stytch Project.
+    # Get the JSON Web Key Set (JWKS) for a project.
+    #
+    # JWKS are rotated every ~6 months. Upon rotation, new JWTs will be signed using the new key set, and both key sets will be returned by this endpoint for a period of 1 month.
+    #
+    # JWTs have a set lifetime of 5 minutes, so there will be a 5 minute period where some JWTs will be signed by the old JWKS, and some JWTs will be signed by the new JWKS. The correct JWKS to use for validation is determined by matching the `kid` value of the JWT and JWKS.
+    #
+    # If you're using one of our [backend SDKs](https://stytch.com/docs/sdks), the JWKS roll will be handled for you.
+    #
+    # If you're using your own JWT validation library, many have built-in support for JWKS rotation, and you'll just need to supply this API endpoint. If not, your application should decide which JWKS to use for validation by inspecting the `kid` value.
     #
     # == Parameters:
     # project_id::
@@ -172,9 +183,10 @@ module Stytch
     def get_jwks(
       project_id:
     )
+      headers = {}
       query_params = {}
       request = request_with_query_params("/v1/sessions/jwks/#{project_id}", query_params)
-      get_request(request)
+      get_request(request, headers)
     end
 
     # MANUAL(Sessions::authenticate_jwt)(SERVICE_METHOD)
@@ -186,12 +198,15 @@ module Stytch
     # If max_token_age_seconds is set and the JWT was issued (based on the "iat" claim) less than
     # max_token_age_seconds seconds ago, then just verify locally and don't call the API
     # To force remote validation for all tokens, set max_token_age_seconds to 0 or call authenticate()
+    # If max_token_age_seconds is not supplied 300 seconds will be used as the default.
     def authenticate_jwt(
       session_jwt,
       max_token_age_seconds: nil,
       session_duration_minutes: nil,
       session_custom_claims: nil
     )
+      max_token_age_seconds = 300 if max_token_age_seconds.nil?
+
       if max_token_age_seconds == 0
         return authenticate(
           session_jwt: session_jwt,
@@ -200,18 +215,14 @@ module Stytch
         )
       end
 
-      decoded_jwt = authenticate_jwt_local(session_jwt)
-      iat_time = Time.at(decoded_jwt['iat']).to_datetime
-      if iat_time + max_token_age_seconds >= Time.now
-        session = marshal_jwt_into_session(decoded_jwt)
-        { 'session' => session }
-      else
-        authenticate(
-          session_jwt: session_jwt,
-          session_duration_minutes: session_duration_minutes,
-          session_custom_claims: session_custom_claims
-        )
-      end
+      session = authenticate_jwt_local(session_jwt, max_token_age_seconds: max_token_age_seconds)
+      return session unless session.nil?
+
+      authenticate(
+        session_jwt: session_jwt,
+        session_duration_minutes: session_duration_minutes,
+        session_custom_claims: session_custom_claims
+      )
     rescue StandardError
       # JWT could not be verified locally. Check with the Stytch API.
       authenticate(
@@ -225,12 +236,20 @@ module Stytch
     # Uses the cached value to get the JWK but if it is unavailable, it calls the get_jwks()
     # function to get the JWK
     # This method never authenticates a JWT directly with the API
-    def authenticate_jwt_local(session_jwt)
+    # If max_token_age_seconds is not supplied 300 seconds will be used as the default.
+    def authenticate_jwt_local(session_jwt, max_token_age_seconds: nil)
+      max_token_age_seconds = 300 if max_token_age_seconds.nil?
+
       issuer = 'stytch.com/' + @project_id
       begin
         decoded_token = JWT.decode session_jwt, nil, true,
                                    { jwks: @jwks_loader, iss: issuer, verify_iss: true, aud: @project_id, verify_aud: true, algorithms: ['RS256'] }
-        decoded_token[0]
+
+        session = decoded_token[0]
+        iat_time = Time.at(session['iat']).to_datetime
+        return nil unless iat_time + max_token_age_seconds >= Time.now
+
+        session = marshal_jwt_into_session(session)
       rescue JWT::InvalidIssuerError
         raise JWTInvalidIssuerError
       rescue JWT::InvalidAudError
@@ -240,6 +259,8 @@ module Stytch
       rescue JWT::IncorrectAlgorithm
         raise JWTIncorrectAlgorithmError
       end
+
+      session
     end
 
     def marshal_jwt_into_session(jwt)
@@ -251,15 +272,17 @@ module Stytch
       reserved_claims = ['aud', 'exp', 'iat', 'iss', 'jti', 'nbf', 'sub', stytch_claim]
       custom_claims = jwt.reject { |key, _| reserved_claims.include?(key) }
       {
-        'session_id' => jwt[stytch_claim]['id'],
-        'user_id' => jwt['sub'],
-        'started_at' => jwt[stytch_claim]['started_at'],
-        'last_accessed_at' => jwt[stytch_claim]['last_accessed_at'],
-        # For JWTs that include it, prefer the inner expires_at claim.
-        'expires_at' => expires_at,
-        'attributes' => jwt[stytch_claim]['attributes'],
-        'authentication_factors' => jwt[stytch_claim]['authentication_factors'],
-        'custom_claims' => custom_claims
+        'session' => {
+          'session_id' => jwt[stytch_claim]['id'],
+          'user_id' => jwt['sub'],
+          'started_at' => jwt[stytch_claim]['started_at'],
+          'last_accessed_at' => jwt[stytch_claim]['last_accessed_at'],
+          # For JWTs that include it, prefer the inner expires_at claim.
+          'expires_at' => expires_at,
+          'attributes' => jwt[stytch_claim]['attributes'],
+          'authentication_factors' => jwt[stytch_claim]['authentication_factors'],
+          'custom_claims' => custom_claims
+        }
       }
     end
     # ENDMANUAL(Sessions::authenticate_jwt)