A production-ready, fully-documented authentication system for Django REST Framework that implements JWT-based authentication with email verification. This project is designed to help developers understand and implement a complete authentication flow without relying on third-party authentication packages.
Many backend developers struggle with implementing authentication in Django REST Framework. This project serves as:
- 📚 Educational Resource: Learn authentication best practices
- 🚀 Production Template: Start your project with solid authentication
- 🔧 Customizable Foundation: Easy to extend and modify for your needs
- 📖 Well-Documented: Every component is thoroughly documented
- ✅ Email-based Authentication - No username required
- ✅ JWT Token Management - Secure token-based auth
- ✅ Token Refresh & Blacklist - Secure token rotation
- ✅ Email Verification - Verify user emails with JWT tokens
- ✅ Password Change - Secure password updates for authenticated users
- ✅ Password Reset - Email-based password recovery
- ✅ Strong Password Validation - Built-in password strength requirements
- ✅ Custom User Model - Email as primary identifier
- ✅ User Profile - Retrieve and manage user information
- ✅ Admin Interface - Enhanced Django admin for user management
- ✅ Swagger UI - Interactive API documentation
- ✅ ReDoc - Beautiful API documentation
- ✅ Type Hints - Full Python type annotations
- ✅ Comprehensive Comments - Well-commented codebase
- ✅ Docker Support - Containerized deployment
- ✅ Docker Compose - One-command development setup
- ✅ Environment Variables - Secure configuration management
- ✅ Production Ready - Optimized settings for deployment
- Python 3.8 or higher
- pip (Python package manager)
- Git
1️⃣ Clone the repository
git clone https://github.com/mobin-gpr/django-rest-auth-jwt.git
cd django-rest-auth-jwt2️⃣ Create and activate virtual environment
# Create virtual environment
python -m venv venv
# Activate on Windows
venv\Scripts\activate
# Activate on macOS/Linux
source venv/bin/activate3️⃣ Install dependencies
pip install -r requirements.txt4️⃣ Set up environment variables
# Copy the example environment file
cp .env.example .env
# Generate a secret key
python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'
# Edit .env and add the generated secret key5️⃣ Run migrations
python manage.py migrate6️⃣ Create superuser (optional)
python manage.py createsuperuser7️⃣ Run the development server
python manage.py runserver🎉 Done! Visit http://localhost:8000/api/docs/swagger/ to see the API documentation.
For a faster setup using Docker:
# Build and start containers
docker-compose up --build
# Run migrations
docker-compose exec web python manage.py migrate
# Create superuser
docker-compose exec web python manage.py createsuperuser| Method | Endpoint | Description | Auth Required |
|---|---|---|---|
POST |
/api/v1/accounts/register/ |
Register a new user | ❌ |
GET |
/api/v1/accounts/confirm_email/<token>/ |
Verify email address | ❌ |
POST |
/api/v1/accounts/resend_confirm_email/ |
Resend verification email | ❌ |
POST |
/api/v1/accounts/jwt/token/ |
Obtain JWT token (login) | ❌ |
POST |
/api/v1/accounts/jwt/token/refresh/ |
Refresh access token | ❌ |
POST |
/api/v1/accounts/jwt/token/verify/ |
Verify token validity | ❌ |
POST |
/api/v1/accounts/jwt/token/blacklist/ |
Blacklist refresh token (logout) | ✅ |
| Method | Endpoint | Description | Auth Required |
|---|---|---|---|
PUT |
/api/v1/accounts/change_password/ |
Change password | ✅ |
POST |
/api/v1/accounts/reset_password/ |
Request password reset | ❌ |
POST |
/api/v1/accounts/set_password/<token>/ |
Set new password after reset | ❌ |
| Method | Endpoint | Description | Auth Required |
|---|---|---|---|
GET |
/api/v1/accounts/profile/ |
Get user profile | ✅ |
| Endpoint | Description |
|---|---|
/api/docs/swagger/ |
Swagger UI documentation |
/api/docs/redoc/ |
ReDoc documentation |
/admin/ |
Django admin interface |
Create a .env file in the project root (use .env.example as template):
# Security
SECRET_KEY=your-secret-key-here
DEBUG=False
ALLOWED_HOSTS=localhost,127.0.0.1
# JWT Configuration
ACCESS_TOKEN_LIFETIME_MINUTES=60
REFRESH_TOKEN_LIFETIME_DAYS=7
# Email Configuration
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password- Swagger UI: Visit
/api/docs/swagger/for interactive API documentation - ReDoc: Visit
/api/docs/redoc/for beautiful, readable API docs
- Email-based authentication (no username field)
- Email verification status tracking
- Enhanced admin interface
- Custom token generation with email in payload
- Secure token decoding with error handling
- Token refresh and blacklisting support
- Asynchronous email sending using threading
- JWT tokens for verification (not stored in database)
- Configurable token expiration
- Django's built-in password validators
- Minimum 8 characters requirement
- Password strength validation
django-rest-auth-jwt/
├── accounts/ # User authentication app
│ ├── migrations/ # Database migrations
│ ├── admin.py # Admin configuration
│ ├── models.py # Custom User model
│ ├── serializers.py # API serializers
│ ├── urls.py # App URL patterns
│ └── views.py # API views
├── config/ # Project configuration
│ ├── settings.py # Django settings
│ ├── urls.py # Main URL configuration
│ └── wsgi.py # WSGI configuration
├── utils/ # Utility modules
│ ├── email.py # Email utilities
│ └── jwt_token.py # JWT token utilities
├── .env.example # Environment variables template
├── .gitignore # Git ignore file
├── docker-compose.yml # Docker Compose configuration
├── Dockerfile # Docker configuration
├── manage.py # Django management script
├── README.md # This file
└── requirements.txt # Python dependencies
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
See CONTRIBUTING.md for detailed guidelines.
This project is licensed under the MIT License - see the LICENSE file for details.
Mobin Ghanbarpour
- GitHub: @mobin-gpr
- Email: mobin.ghanbarpour@yahoo.com
- Django team for the amazing framework
- Django REST Framework team for the powerful toolkit
- Simple JWT team for the authentication library
- All contributors who help improve this project
If this project helped you, please give it a ⭐️! It helps others discover it too.
Have questions or suggestions? Feel free to:
- Open an issue
- Send an email to mobin.ghanbarpour@yahoo.com
- Connect on GitHub
Made with ❤️ by Mobin Ghanbarpour