基于手机号+设备的RESTful身份验证API设计方案咨询

Great question! Let’s break down your two options, weigh their pros and cons, and outline best practices to build a secure, maintainable solution for your enhanced verification flow.

Core Goal Recap #

You want to upgrade from a mobile-number-only verification system to a mobile + device combo (using a client-side cookie as the device identifier) to boost security. The core rule remains: only send a verification code if the target pair (mobile + device) isn’t already marked as verified.

Option 1: Create a New, Dedicated API #

This approach builds a separate endpoint for the mobile+device verification flow, leaving your existing API completely untouched.

Implementation Details #

• New Endpoint: POST /api/users/verification/start-with-device/
• Request: The client sends only the mobile number (just like before)—your backend extracts the device identifier directly from the request’s cookie (never let the client pass this value manually to avoid tampering):

  {
    "mobile": "9849735434"
  }
  

• Backend Logic:
  1. Pull the device_id from the secure, HttpOnly cookie you’ve set on the client.
  2. Check your database for a verified entry matching the mobile + device_id pair.
  3. Return {"isVerified": true} if the pair exists (no code sent), or {"isVerified": false} if it doesn’t (send the verification code to the mobile number).
• Database Update: Add a table or column to track verified (mobile, device_id) pairs (replacing or supplementing your existing mobile-only records).

Pros #

• No Breaking Changes: Your original API keeps working for any clients that still rely on mobile-only verification.
• Clean, Single Responsibility: The new endpoint only handles the enhanced verification flow—no messy conditional logic to debug.
• Low Risk: You avoid introducing bugs to your existing, already-stable codebase.

Cons #

• Extra Endpoint: You’ll have two verification endpoints to maintain, though this is a minor tradeoff for stability.

Option 2: Modify the Existing API with a Mode Switch #

This approach updates your current endpoint to support both verification modes via an optional parameter.

Implementation Details #

• Updated Endpoint: Keep using POST /api/users/verification/start/, but add an optional verify_mode parameter:

  {
    "mobile": "9849735434",
    "verify_mode": "mobile_device" // Optional; default to "mobile_only"
  }
  

• Backend Logic:
  1. If verify_mode is missing or set to "mobile_only", run your original mobile-number-only check.
  2. If verify_mode is "mobile_device", pull the device_id from the cookie and check the mobile + device_id pair in your database.
  3. Return {"isVerified": true/false} based on the check, and send the code only if needed.

Pros #

• Unified API: Clients only need to interact with one endpoint, simplifying integration and documentation.
• Flexibility: You can easily toggle between verification modes as your needs change.

Cons #

• Increased Complexity: Your endpoint now has conditional logic to handle two distinct flows, making the code harder to maintain and debug over time.
• Compatibility Risks: If you don’t set a sensible default (like "mobile_only"), you might break existing clients that don’t send the new parameter.

Recommendation #

• Choose Option 1 if: Your existing API is used by multiple clients (web, mobile, third-party services) and you want to avoid breaking anything. This is the safer, more maintainable choice for most production systems.
• Choose Option 2 if: You have a small number of clients, or you prioritize a clean API surface over absolute backward compatibility. Just be sure to set verify_mode’s default to "mobile_only" to preserve existing functionality.

Critical Security Best Practices #

Whichever option you pick, don’t skip these safeguards:

• Secure the Device Cookie: Set the cookie as HttpOnly (prevents XSS theft) and Secure (only sent over HTTPS). Generate the device_id on the backend—never let the client create or modify it.
• Expire Verified Pairs: Add an expiration date to verified mobile + device entries. This forces re-verification if a device is inactive for too long.
• Force Codes for New Devices: If a user tries to verify their number on an unrecognized device, always send a code—even if their number is already verified on other devices.

内容的提问来源于stack exchange，提问作者Sahil Sharma