Skip to content

Authentication

Overview

Jend-Z uses JWT (JSON Web Token) based authentication with email as the primary login method. The authentication system supports user registration, login, password reset via OTP, and immediate token generation. All authentication endpoints use the /api/auth/ prefix.

Authentication Flow

The platform uses a dual-token system:

  • Access Token: Short-lived token for API requests (default: 1 hour)
  • Refresh Token: Long-lived token for obtaining new access tokens (default: 30 days)

For web applications, refresh tokens are stored as secure HTTP-only cookies. For mobile applications, both tokens are returned in the response body.

Authentication Endpoints

1. User Registration

Endpoint: POST /api/auth/register/

Description: Creates a new user account and immediately returns JWT tokens for seamless authentication.

Content-Type: multipart/form-data (supports file uploads for profile picture)

Request Body:

{
  "email": "user@example.com",
  "username": "unique_username",
  "display_name": "Display Name",
  "password": "securepassword123",
  "bio": "Optional bio text",
  "profile_picture": "image_file",
  "location": "location_id_uuid",
  "referrer_code": "OPTIONAL_REFERRAL_CODE",
  "ref_source": "instagram",
  "ref_medium": "social",
  "ref_campaign": "summer2024"
}

Required Fields:

  • email
  • username
  • display_name
  • password

Success Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": "uuid-string",
    "email": "user@example.com",
    "username": "unique_username",
    "display_name": "Display Name",
    "is_verified": false,
    "bio": "Optional bio text",
    "profile_picture": "https://example.com/media/profile_pictures/image.jpg",
    "website": null,
    "relationship_status": null,
    "banner": null,
    "location": {
      "id": "location-uuid",
      "name": "Location Name"
    },
    "store": null,
    "owned_communities": [],
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

Referral System:

  • If referrer_code is provided, the system attempts to link the new user to an existing ambassador
  • Invalid referral codes are silently ignored (no error thrown)
  • Analytics tracking supports ref_source, ref_medium, and ref_campaign for attribution

Web Browser Behavior:

  • Sets refresh_token as an HTTP-only cookie with 30-day expiration
  • Cookie settings: httponly=True, secure=True, samesite="Lax"

2. User Login

Endpoint: POST /api/auth/login/

Description: Authenticates a user and returns JWT tokens. Supports login with either email or username.

Request Body:

{
  "username": "user@example.com",
  "password": "securepassword123"
}

Note: Despite the field name being username, you can provide either the actual username or email address.

Success Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": "uuid-string",
    "email": "user@example.com",
    "username": "unique_username",
    "display_name": "Display Name",
    "is_verified": false,
    "bio": "User bio",
    "profile_picture": "https://example.com/media/profile_pictures/image.jpg",
    "website": "https://userwebsite.com",
    "relationship_status": "looking_for_love",
    "banner": "https://example.com/media/users/banners/banner.jpg",
    "location": {
      "id": "location-uuid",
      "name": "Lagos, Nigeria"
    },
    "store": {
      "id": "store-uuid",
      "name": "User's Store",
      "description": "Store description"
    },
    "owned_communities": [
      {
        "id": "community-uuid",
        "name": "Lagos Tech Hub",
        "description": "Community for tech enthusiasts"
      }
    ],
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Error Response:

{
  "error": "Invalid credentials"
}

Web Browser Behavior:

  • Sets refresh_token as an HTTP-only cookie with 30-day expiration
  • Cookie settings: httponly=True, secure=True, samesite="Lax"

3. Token Refresh

Endpoint: POST /api/auth/refresh/

Description: Refreshes access token using the HTTP-only cookie. Automatically blacklists the old refresh token and issues a new one.

Authentication: Refresh token cookie required

Request Body: Empty

Success Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Error Responses:

{
  "error": "Refresh token missing"
}

{
  "error": "Invalid or blacklisted refresh token"
}

{
  "error": "User not found"
}

4. Logout

Endpoint: POST /api/auth/logout/

Description: Logs out the user by removing the refresh token cookie.

Authentication: None required

Response:

{
  "message": "Logged out successfully"
}

Password Reset System

The password reset system uses a 6-digit OTP (One-Time Password) sent via email.

OTP Security Features

  • Expiration: OTPs expire after 10 minutes
  • Rate Limiting: Maximum 5 failed attempts before lockout
  • Single Use: Each OTP can only be used once
  • Auto-lockout: Account locks after 5 failed attempts until new OTP is requested

1. Request Password Reset

Endpoint: POST /api/auth/password-reset/request/

Description: Sends a 6-digit OTP to the user's email address.

Request Body:

{
  "email": "user@example.com"
}

Success Response:

{
  "detail": "OTP sent to email."
}

Error Response:

{
  "email": ["User with this email does not exist."]
}

2. Confirm Password Reset

Endpoint: POST /api/auth/password-reset/confirm/

Description: Verifies the OTP and sets a new password.

Request Body:

{
  "email": "user@example.com",
  "otp": "123456",
  "new_password": "newsecurepassword123"
}

Success Response:

{
  "detail": "Password has been reset successfully."
}

Error Responses:

{
  "non_field_errors": ["Invalid user."]
}

{
  "non_field_errors": ["Invalid or expired OTP."]
}

{
  "non_field_errors": ["OTP has expired or is invalid."]
}

{
  "non_field_errors": ["Too many failed attempts. Please request a new OTP."]
}

Authentication Headers

For all authenticated endpoints, include the access token in the Authorization header:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Security Features

Password Security

  • Minimum 8 characters required
  • Passwords are hashed using Django's default PBKDF2 algorithm

OTP Security

  • 6-digit numeric codes
  • 10-minute expiration
  • 5 attempt maximum before lockout
  • Codes are invalidated after successful use

Token Security

  • Access tokens expire after 1 hour (configurable)
  • Refresh tokens expire after 30 days (configurable)
  • Old refresh tokens are blacklisted when new ones are issued
  • Secure HTTP-only cookies for web applications

Error Handling

Common HTTP Status Codes

  • 200 OK: Successful request
  • 201 Created: Account created successfully
  • 400 Bad Request: Invalid request data
  • 401 Unauthorized: Authentication required or invalid token
  • 500 Internal Server Error: Server error

Error Response Format

Validation errors follow Django REST Framework format:

{
  "field_name": ["Error message for this field"],
  "non_field_errors": ["General error message"]
}

General errors:

{
  "error": "Error message"
}