Token-Based Authentication for Stateless APIs

Stateful vs. Stateless Authentication

The core difference between session-based and token-based authentication lies in the concept of state.

• Stateful (SessionAuthentication): The server creates a session for a user upon login and stores this session data. For every subsequent request, the server looks up the session ID sent by the client (usually in a cookie) to identify the user. The "state" (the user's session) lives on the server.
• Stateless (Token Authentication): The server does not store any session information. After the initial login, the server gives the client a self-contained token. For every subsequent request, the client includes this token. The server can validate the token on its own without needing to look up any stored data.

The following diagram illustrates this key difference. With token authentication, we follow the stateless model, where each request from the client contains all the information needed for the server to process it.

This stateless nature is a major reason why token authentication is preferred for modern APIs that serve a variety of clients (web, mobile, other services).

Introducing JSON Web Tokens (JWT)

While DRF has a simple built-in token system, a more powerful and widely adopted standard is the JSON Web Token (JWT), often pronounced "jot".

A JWT is a compact, self-contained token that securely transmits information between parties as a JSON object. The key benefits are:

• Stateless: As we discussed, the token contains all the necessary user information (like their ID) in its data payload, reducing the need for database lookups on every request.
• Expiration: JWTs have a built-in expiration time, which is a crucial security feature.
• Industry Standard: Being a well-defined standard (RFC 7519), it has wide support across different languages and frameworks.

To implement JWT authentication in DRF, we'll use djangorestframework-simplejwt, a popular and well-maintained package that handles all the complexities for us.

Implementing JWT Authentication with simple-jwt

This video provides a complete, practical walkthrough of setting up simple-jwt from start to finish. We'll follow its steps to integrate JWT into our project.

After these steps, your settings.py should have a REST_FRAMEWORK dictionary that looks something like this:

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
        'rest_framework.authentication.SessionAuthentication', 
    ),
    # ... other settings
}

DRF tries authentication classes in order. With this setup, it will first try to authenticate using a JWT. If that fails or isn't provided, it will fall back to SessionAuthentication, ensuring the browsable API continues to work as before.

Obtaining and Using Tokens

simple-jwt provides views that you can add to your urls.py to allow clients to get and refresh tokens.

You've now created two crucial endpoints:

• /api/token/: A client sends a POST request here with their username and password. If valid, they receive an access token and a refresh token.
• /api/token/refresh/: A client sends their refresh token here to get a new access token when the old one expires.

The access token is the one you'll use to authenticate most requests. It's short-lived (e.g., 5-15 minutes). The refresh token is long-lived (e.g., hours or days) and its only purpose is to get new access tokens without forcing the user to log in again. This separation is a key security pattern.

Now, let's see this in action.

DRF's Built-in TokenAuthentication

It's worth noting that DRF also provides a simpler, built-in token system. While simple-jwt is generally recommended for its features, you should be aware of the built-in option for simpler use cases.

This built-in system creates a single, permanent token for each user and stores it in the database. Every request requires a database lookup to validate the token, making it stateful in a way, although it doesn't use Django sessions. For most modern projects, simple-jwt is the superior choice.

Conclusion

Congratulations! You have successfully implemented a modern, secure, and stateless authentication system for your API. This is a fundamental skill for any backend developer building services that need to communicate with diverse clients.

Key Takeaways:

• Stateless vs. Stateful: Token-based authentication is stateless, making APIs more scalable and flexible than stateful, session-based systems.
• JWT is the Standard: JSON Web Tokens (JWT) are the modern standard for API authentication, offering features like self-contained user data and expiration times.
• simple-jwt Workflow:
  1. Install and configure djangorestframework-simplejwt.
  2. Add its URL endpoints for obtaining and refreshing tokens.
  3. Clients exchange username/password for an access and refresh token pair.
  4. The short-lived access token is sent with each request in the Authorization: Bearer <token> header.
• Access vs. Refresh: Access tokens grant access to resources, while long-lived refresh tokens are used solely to obtain new access tokens.

Preview of the Next Lesson:
So far, our authentication classes determine who a user is. Now we need to control what they are allowed to do. In the next lesson, we will dive into Permissions. We'll learn how to use DRF's built-in permission classes like IsAuthenticated and IsAdminUser to protect our API views and ensure that only the right users can perform certain actions.