feat: support two-factor sign-in for API clients with a signed token

When a password sign-in needs a second factor and the request is not
navigational, respond `401` with a `two_factor_token`. The security key
options and two-factor endpoints accept it in place of the session.
Two-factor sign-in follows `skip_session_storage` (`:params_auth`).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: RenzoMinelli

CHANGELOG.md

@@ -8,10 +8,12 @@
 - Add the `:cache` challenge store, which keeps challenges in `Rails.cache` instead of the session. [#152](https://github.com/cedarcode/devise-webauthn/pull/152) [@RenzoMinelli]
 - Accept `public_key_credential` as a JSON object as well as a JSON string. [#153](https://github.com/cedarcode/devise-webauthn/pull/153) [@RenzoMinelli]
 - Respond with JSON from the passkey and security key controllers when the request is not navigational, through Devise's responder. [#153](https://github.com/cedarcode/devise-webauthn/pull/153) [@RenzoMinelli]
+- Return a `two_factor_token` to API clients when a password sign-in needs a second factor, and accept it instead of the session to finish two-factor sign-in. [#154](https://github.com/cedarcode/devise-webauthn/pull/154) [@RenzoMinelli]
 
 ### Changed
 
 - Passkey sign-in no longer stores the user in the session when `skip_session_storage` includes `:params_auth`, the same as password sign-in. [#153](https://github.com/cedarcode/devise-webauthn/pull/153) [@RenzoMinelli]
+- Two-factor sign-in with a security key follows the same `skip_session_storage` setting. [#154](https://github.com/cedarcode/devise-webauthn/pull/154) [@RenzoMinelli]
 - The WebAuthn options controllers only call `skip_forgery_protection` when it is defined, so they load under an `ActionController::API` parent. [#153](https://github.com/cedarcode/devise-webauthn/pull/153) [@RenzoMinelli]
 
 ## [v0.5.0](https://github.com/cedarcode/devise-webauthn/compare/v0.4.0...v0.5.0/) - 2026-07-13

README.md

@@ -188,6 +188,17 @@ Send `public_key_credential` as the JSON object your WebAuthn library returns. F
 | Add passkey | `POST /users/passkeys` with `name` and `public_key_credential` (authenticated) | `201` with the passkey, or `422` with `errors` |
 | Delete passkey | `DELETE /users/passkeys/:id` (authenticated) | `204` |
 
+### Two-factor authentication
+
+When a user with security keys signs in with a password, the response is `401` with a `two_factor_token`. Send that token to `POST /users/security_key_authentication_options` and to `POST /users/two_factor_authentication` together with `public_key_credential`. The token expires after 5 minutes (`Devise::Webauthn::TwoFactorToken.expires_in`).
+
+devise-jwt only issues a token on `POST /users/sign_in` by default. Add the 2FA path:
+```ruby
+config.jwt do |jwt|
+  jwt.dispatch_requests = [["POST", %r{^/users/two_factor_authentication$}]]
+end
+```
+
 ## Customization
 
 ### Customizing Views

app/controllers/devise/security_key_authentication_options_controller.rb

@@ -3,6 +3,7 @@
 module Devise
   class SecurityKeyAuthenticationOptionsController < DeviseController
     include Devise::Webauthn::ChallengeStoreAccess
+    include Devise::Webauthn::PendingTwoFactorSignIn
 
     skip_forgery_protection if respond_to?(:skip_forgery_protection)
 
@@ -23,7 +24,7 @@ def create
     private
 
     def set_resource
-      @resource = resource_class.find(session[:current_authentication_resource_id])
+      @resource = resource_class.find(pending_two_factor_sign_in(resource_name)&.fetch("id"))
     end
   end
 end

app/controllers/devise/two_factor_authentications_controller.rb

@@ -2,6 +2,8 @@
 
 module Devise
   class TwoFactorAuthenticationsController < DeviseController
+    include Devise::Webauthn::PendingTwoFactorSignIn
+
     prepend_before_action :set_resource, only: :new
     prepend_before_action :ensure_sign_in_initiated
     prepend_before_action :require_no_authentication
@@ -25,14 +27,18 @@ def auth_options
     private
 
     def ensure_sign_in_initiated
-      return if session[:current_authentication_resource_id].present?
+      return if pending_two_factor_sign_in(resource_name).present?
 
       set_flash_message! :alert, :sign_in_not_initiated, scope: :"devise.failure"
-      redirect_to new_session_path(resource_name)
+      if is_navigational_format?
+        redirect_to new_session_path(resource_name)
+      else
+        render json: { error: find_message(:sign_in_not_initiated, scope: :"devise.failure") }, status: :unauthorized
+      end
     end
 
     def set_resource
-      @resource = resource_class.find(session[:current_authentication_resource_id])
+      @resource = resource_class.find(pending_two_factor_sign_in(resource_name)["id"])
     end
   end
 end

lib/devise/strategies/database_authenticatable.rb

@@ -11,12 +11,14 @@ def authenticate!
         hashed = false
 
         if validate(resource){ hashed = true; resource.valid_password?(password) }
-          if second_factor_enabled?(resource)
+          if second_factor_enabled?(resource) && navigational_request?
             session[:current_authentication_resource_id] = resource.id
             session[:current_authentication_remember_me] = remember_me?
             request.flash[:notice] = two_factor_required_message
             request.commit_flash
             redirect!(two_factor_authentication_path, {}, message: two_factor_required_message)
+          elsif second_factor_enabled?(resource)
+            custom!(two_factor_required_response(resource))
           else
             remember_me(resource)
             resource.after_database_authentication
@@ -39,6 +41,17 @@ def two_factor_authentication_path
         Rails.application.routes.url_helpers.send(:"new_#{scope}_two_factor_authentication_path")
       end
 
+      def navigational_request?
+        Devise.navigational_formats.include?(request.format.try(:ref))
+      end
+
+      def two_factor_required_response(resource)
+        token = Devise::Webauthn::TwoFactorToken.generate(resource, scope: scope, remember_me: remember_me?)
+        body = { error: two_factor_required_message, two_factor_token: token }.to_json
+
+        [401, { "Content-Type" => "application/json" }, [body]]
+      end
+
       def two_factor_required_message
         I18n.t(:"#{scope}.two_factor_required", resource_name: scope, scope: "devise.failure", default: :two_factor_required)
       end

lib/devise/strategies/webauthn_two_factor_authenticatable.rb

@@ -5,18 +5,24 @@ module Strategies
     class WebauthnTwoFactorAuthenticatable < Devise::Strategies::Base
       include Devise::Webauthn::ChallengeStoreAccess
       include Devise::Webauthn::PublicKeyCredentialParam
+      include Devise::Webauthn::PendingTwoFactorSignIn
 
       def valid?
         public_key_credential_param.present? &&
-          session[:current_authentication_resource_id].present? &&
+          pending_two_factor_sign_in(scope).present? &&
           challenge_store.pending?(:two_factor_authentication)
       end
 
+      def store?
+        super && mapping.to.skip_session_storage.exclude?(:params_auth)
+      end
+
       # rubocop:disable Metrics/AbcSize
       def authenticate!
         expected_challenge = challenge_store.consume(:two_factor_authentication)
         credential_from_params = WebAuthn::Credential.from_get(public_key_credential_param)
-        resource = resource_class.find_by(id: session[:current_authentication_resource_id])
+        pending_sign_in = pending_two_factor_sign_in(scope)
+        resource = resource_class.find_by(id: pending_sign_in["id"])
         stored_credential = resource&.webauthn_credentials&.find_by(external_id: credential_from_params.id)
 
         return fail!(:webauthn_credential_not_found) if stored_credential.blank?
@@ -26,11 +32,10 @@ def authenticate!
 
         verify_credential(credential_from_params, stored_credential, expected_challenge)
 
-        resource.remember_me = session[:current_authentication_remember_me] if resource.respond_to?(:remember_me=)
+        resource.remember_me = pending_sign_in["remember_me"] if resource.respond_to?(:remember_me=)
         success!(resource)
 
-        session.delete(:current_authentication_resource_id)
-        session.delete(:current_authentication_remember_me)
+        clear_pending_two_factor_sign_in
       rescue WebAuthn::Error
         fail!(:webauthn_credential_verification_failed)
       end

lib/devise/webauthn.rb

@@ -8,6 +8,8 @@
 require_relative "webauthn/challenge_stores/cache"
 require_relative "webauthn/challenge_store_access"
 require_relative "webauthn/public_key_credential_param"
+require_relative "webauthn/two_factor_token"
+require_relative "webauthn/pending_two_factor_sign_in"
 require_relative "webauthn/engine"
 require_relative "webauthn/helpers/credentials_helper"
 require_relative "webauthn/routes"

lib/devise/webauthn/pending_two_factor_sign_in.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Devise
+  module Webauthn
+    module PendingTwoFactorSignIn
+      private
+
+      # Browsers keep the pending sign-in in the session; API clients send back the `two_factor_token`.
+      def pending_two_factor_sign_in(scope)
+        resource_id = request.session[:current_authentication_resource_id]
+        if resource_id.present?
+          { "id" => resource_id, "remember_me" => request.session[:current_authentication_remember_me] }
+        else
+          TwoFactorToken.read(params[:two_factor_token], scope: scope)
+        end
+      end
+
+      def clear_pending_two_factor_sign_in
+        request.session.delete(:current_authentication_resource_id)
+        request.session.delete(:current_authentication_remember_me)
+      end
+    end
+  end
+end

lib/devise/webauthn/two_factor_token.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Devise
+  module Webauthn
+    class TwoFactorToken
+      PURPOSE = :devise_webauthn_two_factor
+
+      cattr_accessor :expires_in, default: 5.minutes
+
+      def self.generate(resource, scope:, remember_me:)
+        payload = { "id" => resource.id, "scope" => scope.to_s, "remember_me" => remember_me }
+        verifier.generate(payload, purpose: PURPOSE, expires_in: expires_in)
+      end
+
+      def self.read(token, scope:)
+        return unless token.is_a?(String)
+
+        payload = verifier.verified(token, purpose: PURPOSE)
+        payload if payload.is_a?(Hash) && payload["scope"] == scope.to_s
+      end
+
+      def self.verifier
+        Rails.application.message_verifier(PURPOSE)
+      end
+    end
+  end
+end

spec/requests/devise/api_client_spec.rb

@@ -128,4 +128,47 @@ def request_registration_challenge
       expect(user.passkeys).to be_empty
     end
   end
+
+  describe "two-factor sign-in" do
+    let!(:security_key) { create_credential_for(user, :second_factor) }
+
+    def request_two_factor_token
+      api_post account_session_path, account: { email: user.email, password: password }
+      response.parsed_body["two_factor_token"]
+    end
+
+    def security_key_assertion(token)
+      api_post account_security_key_authentication_options_path, two_factor_token: token
+      client.get(challenge: response.parsed_body["challenge"], allow_credentials: [security_key.external_id])
+    end
+
+    it "responds to the password step with 401 and a two-factor token" do
+      api_post account_session_path, account: { email: user.email, password: password }
+
+      expect(response).to have_http_status(:unauthorized)
+      expect(response.parsed_body).to include("error" => I18n.t("devise.failure.two_factor_required"),
+                                              "two_factor_token" => be_present)
+    end
+
+    it "signs in with the two-factor token and a security key and does not store the user in the session" do
+      token = request_two_factor_token
+      assertion = security_key_assertion(token)
+
+      api_post account_two_factor_authentication_path, two_factor_token: token, public_key_credential: assertion
+
+      expect(response).to have_http_status(:created)
+      expect(response.parsed_body["email"]).to eq(user.email)
+      expect(session["warden.user.account.key"]).to be_nil
+    end
+
+    it "rejects a tampered two-factor token" do
+      token = request_two_factor_token
+      assertion = security_key_assertion(token)
+
+      api_post account_two_factor_authentication_path, two_factor_token: "#{token}x", public_key_credential: assertion
+
+      expect(response).to have_http_status(:unauthorized)
+      expect(response.parsed_body["error"]).to eq(I18n.t("devise.failure.sign_in_not_initiated"))
+    end
+  end
 end