Skip to main content

Authentication

ThePlugg backend uses phone number-based authentication with OTP (One-Time Password) verification.

Authentication Flow​

  1. User provides phone number and role
  2. Backend generates and sends OTP via SMS
  3. User submits OTP code
  4. Backend verifies OTP and creates/returns user session

OTP Generation​

  • 5-digit numeric code
  • Valid for 10 minutes
  • Automatically expires after verification or timeout

Rate Limiting​

OTP requests are rate-limited:

  • 1 SMS per minute per phone number
  • 30 SMS per day per phone number
  • Daily limit resets at midnight UTC

See SMS Integration for details.

User Roles​

The platform supports three roles:

  • PROVIDER - Service providers
  • SERVICE_SEEKER - Customers seeking services
  • ADMIN - Platform administrators

JWT Tokens​

Currently, the API uses session-based authentication. JWT tokens can be implemented for stateless authentication if needed.

API Key Authentication (Admin)​

Admin endpoints require an API key in the request header:

x-api-key: your-admin-api-key

Set the API key in environment variables:

API_KEY=your-secure-admin-api-key

Security Best Practices​

  1. OTP Expiry: OTPs expire after 10 minutes
  2. Rate Limiting: Prevents SMS spam and abuse
  3. One-Time Use: Each OTP can only be verified once
  4. Phone Validation: Phone numbers are validated before sending OTP
  5. No OTP in Production: OTP codes are never returned in API responses in production