Authentication Guide

ModestWear API uses JWT (JSON Web Tokens) for authentication with support for traditional email/password and social OAuth.

Authentication Methods

1. Email/Password Registration

Endpoint: POST /api/users/register/

Required Fields:

  • email (string) - User’s email address

  • password (string) - Must meet security requirements

Optional Fields:

  • full_name (string) - Automatically split into first/last name

  • phone_number (string) - Contact number

Example:

curl -X POST https://modestwear.onrender.com/api/users/register/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "full_name": "Jane Doe",
    "phone_number": "+27123456789"
  }'

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "email": "user@example.com",
      "username": "user",
      "is_verified": false
    },
    "tokens": {
      "access_token": "eyJ0eXAiOiJKV1Qi...",
      "refresh_token": "eyJ0eXAiOiJKV1Qi...",
      "token_type": "Bearer",
      "expires_in": 900
    },
    "email_verified": false
  }
}

Note

A verification email is automatically sent. Users can browse but may have limited access until verified.

2. Email Verification

Endpoint: POST /api/users/verify-email/

Parameters:

  • token (string) - Verification token from email

Example:

curl -X POST https://modestwear.onrender.com/api/users/verify-email/ \
  -H "Content-Type: application/json" \
  -d '{
    "token": "abc123xyz..."
  }'

3. Login

Endpoint: POST /api/users/login/

Parameters:

  • email (string)

  • password (string)

Example:

curl -X POST https://modestwear.onrender.com/api/users/login/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'

Response:

{
  "data": {
    "user": {
      "id": 1,
      "email": "user@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "tokens": {
      "access_token": "eyJ0eXAiOiJKV1Qi...",
      "refresh_token": "eyJ0eXAiOiJKV1Qi...",
      "token_type": "Bearer",
      "expires_in": 900
    },
    "email_verified": true
  }
}

4. Google OAuth Login

Endpoint: POST /api/users/social/google/

Parameters:

  • token (string) - Google ID token from frontend

Flow:

  1. Frontend initiates Google OAuth

  2. Google returns ID token

  3. Send token to this endpoint

  4. Backend verifies with Google

  5. Returns JWT tokens

Example:

curl -X POST https://modestwear.onrender.com/api/users/social/google/ \
  -H "Content-Type: application/json" \
  -d '{
    "token": "google_id_token_here"
  }'

Tip

Social users are automatically verified since Google confirms their email.

Token Management

Access Token

  • Lifetime: 15 minutes

  • Usage: Include in Authorization header for all authenticated requests

  • Format: Authorization: Bearer <access_token>

Refresh Token

  • Lifetime: 14 days

  • Usage: Get new access token without re-login

  • Rotation: New refresh token issued on each refresh

Token Refresh

Endpoint: POST /api/users/token/refresh/

Parameters:

  • refresh_token (string)

Example:

curl -X POST https://modestwear.onrender.com/api/users/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJ0eXAiOiJKV1Qi..."
  }'

Response:

{
  "success": true,
  "data": {
    "access_token": "new_access_token",
    "refresh_token": "new_refresh_token",
    "token_type": "Bearer",
    "expires_in": 900
  }
}

Using Tokens

Include the access token in all authenticated requests:

curl https://modestwear.onrender.com/api/orders/cart/ \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1Qi..."

Logout

Endpoint: POST /api/users/logout/

Parameters:

  • refresh_token (string, optional)

Example:

curl -X POST https://modestwear.onrender.com/api/users/logout/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJ0eXAiOiJKV1Qi..."
  }'

Warning

Logout blacklists the refresh token. The access token remains valid until expiration.

Security Features

  • Password Validation: Minimum 8 characters, not too common, not all numeric

  • Account Lockout: 5 failed attempts = 15-minute lockout

  • Token Blacklisting: Refresh tokens blacklisted on logout/rotation

  • Email Verification: Required for full access

  • HTTPS Only: All production traffic encrypted

Error Responses

Invalid Credentials

{
  "success": false,
  "error": "Invalid email or password"
}

Account Locked

{
  "success": false,
  "error": "Account temporarily locked due to multiple failed attempts",
  "lockout": true
}

Token Expired

{
  "detail": "Token is invalid or expired",
  "code": "token_not_valid"
}

Best Practices

  1. Store tokens securely - Use httpOnly cookies or secure storage

  2. Refresh proactively - Refresh before access token expires

  3. Handle 401 errors - Redirect to login when token invalid

  4. Logout on sensitive actions - Clear tokens on password change

  5. Use HTTPS - Never send tokens over HTTP

Next Steps