Building a personal note-taking API that keeps each user's data private is a common challenge. Most tutorials rely on session-based authentication, but that breaks down when your frontend and backend are hosted on different domains. JSON Web Tokens (JWT) offer a stateless, cross-domain solution. In this guide, you'll learn the ten key concepts to create a Django REST Framework API with SimpleJWT, where users can register, log in, and manage notes that only they can access. By the end, you'll have a scoped API that protects user data from unauthorized access.
1. Why JWT Over Sessions for Modern APIs?
Session authentication works well when the frontend and backend share the same server. But once you separate them—for example, a React app on Netlify talking to a Django API on PythonAnywhere—cookies don't travel across domains, and login breaks. JWT solves this. A JWT token is a self-contained JSON object that includes user information and an expiration time. The server only needs to verify the token's signature, not store session data. This makes authentication stateless, scalable, and ideal for APIs consumed by mobile apps or single-page applications. With SimpleJWT, you get built-in endpoints for obtaining and refreshing tokens, simplifying the process.
2. Setting Up Django and DRF Project Structure
Start by creating a virtual environment and installing Django, Django REST Framework, and djangorestframework-simplejwt. Then create your project and a dedicated app (e.g., notes). Register rest_framework and your app in INSTALLED_APPS. This foundation ensures your API can handle requests and authentication. Use Django's project structure to separate concerns: your main project folder holds settings and URLs, while the app contains models, views, and serializers. Proper setup avoids common pitfalls like missing dependencies or wrong import paths.
3. Creating a Custom User Model
Django's default User model works, but a custom model gives you flexibility. Define a model that uses email as the unique identifier instead of a username. Subclass AbstractBaseUser and PermissionsMixin, add fields like email and is_active, and specify USERNAME_FIELD = 'email'. Then, set AUTH_USER_MODEL in settings to point to your custom model. Run migrations. This approach future‑proofs your API—if you later need additional fields (e.g., profile picture), you can add them without rebuilding the database.
4. Defining the Note Model and User Relationship
Each note must belong to exactly one user. Use a ForeignKey to the custom user model with on_delete=models.CASCADE. Include fields like title, content, and created_at. Override the __str__ method for readability. After defining the model, create and apply migrations. Register the model in admin.py so you can inspect data during development. This relationship is the core of scoping—by linking notes to users, you can later filter queries to show only the authenticated user's notes.
5. Serializers for User Registration and Notes
Serializers convert data between Python objects and JSON. Create a UserSerializer with fields for email and password. Override create to use create_user so passwords are hashed. For notes, create a NoteSerializer with fields id, title, content, and created_at. Make the owner field read-only—the view will set it automatically from the authenticated user. This ensures users can't forge notes belonging to others. Use Meta class to define model and fields.
6. Configuring SimpleJWT for Token Authentication
In settings.py, add 'rest_framework_simplejwt.authentication.JWTAuthentication' to DEFAULT_AUTHENTICATION_CLASSES. Set DEFAULT_PERMISSION_CLASSES to ['rest_framework.permissions.IsAuthenticated'] to protect all views by default. Then add token endpoints to your project URLs: path('api/token/', TokenObtainPairView.as_view()) and path('api/token/refresh/', TokenRefreshView.as_view()). SimpleJWT handles token creation and refresh, giving you a solid authentication layer with minimal code.
7. Building the Registration and Login Logic
Create a registration view (e.g., RegisterView) that accepts POST requests with email and password. Use the UserSerializer to validate and create a new user. Return the user data and a success message. For login, the built-in TokenObtainPairView accepts email and password and returns an access and refresh token. The client stores these tokens and includes the access token in the Authorization header as Bearer for every subsequent request. This stateless flow is easy to implement and test.
8. Implementing Scoped Views with ViewSets
Use a ModelViewSet for notes. Override get_queryset to filter by request.user—this ensures users only see their own notes. For creation, override perform_create to set owner=request.user. This automatically scopes all operations (list, retrieve, update, delete) to the authenticated user. Use DRF's permissions.IsAuthenticated to block unauthenticated access. With a ViewSet, you get all CRUD endpoints from a single class, reducing boilerplate and keeping code clean.
9. Preventing ID Enumeration Attacks
Even with scoping, a malicious user might try to guess note IDs. If your API returns 404 for notes not belonging to the user, an attacker could infer valid IDs by observing responses. To mitigate this, always return a generic 404 regardless of whether the note exists or is owned. Another approach: use UUIDs instead of sequential integers for note IDs. This makes IDs unpredictable. Additionally, avoid exposing ownership information in error messages. Your scoped queryset already handles this naturally—show no difference between a missing note and an unauthorized note.
10. Testing with Postman and Handling Token Expiry
Test your API with Postman: first register a user, then obtain tokens via /api/token/. Use the access token to create and list notes. Verify scoping by creating a second user and confirming they see no cross‑user data. Access tokens typically expire after 5 minutes. When you get a 401, use the refresh endpoint to obtain a new access token. SimpleJWT's TokenRefreshView takes a valid refresh token and returns a new access token. For a smooth user experience, implement automatic token refresh on the client side before the token expires.
Building a scoped note-taking API with Django REST Framework and SimpleJWT is a straightforward process that gives you robust authentication and data isolation. You've learned why JWT beats sessions for modern apps, how to set up custom user models, create scoped views, and secure your API against common attacks. With these ten steps, you can extend the pattern to any resource—tasks, journal entries, or project files. Now it's your turn to implement and customize!