In this tutorial you are going to learn how to implement Token-based authentication using Django REST Framework (DRF). The token authentication works by exchanging username and password for a token that will be used in all subsequent requests so to identify the user on the server side.
The specifics of how the authentication is handled on the client side vary a lot depending on the technology/language/framework you are working with. The client could be a mobile application using iOS or Android. It could be a desktop application using Python or C++. It could be a Web application using PHP or Ruby.
But once you understand the overall process, it’s easier to find the necessary resources and documentation for your specific use case.
Token authentication is suitable for client-server applications, where the token is safely stored. You should never expose your token, as it would be (sort of) equivalent of a handing out your username and password.
Table of Contents
- Setting Up The REST API Project (If you already know how to start a DRF project you can skip this)
- Implementing the Token Authentication
- User Requesting a Token
Setting Up The REST API Project
So let’s start from the very beginning. Install Django and DRF:
Create a new Django project:
Navigate to the myapi folder:
Start a new app. I will call my app core:
Here is what your project structure should look like:
Add the core app (you created) and the rest_framework app (you installed) to the
INSTALLED_APPS, inside the
Return to the project root (the folder where the manage.py script is), and migrate the database:
Let’s create our first API view just to test things out:
Now register a path in the urls.py module:
So now we have an API with just one endpoint
/hello/ that we can perform
GET requests. We can use the browser to
consume this endpoint, just by accessing the URL
We can also ask to receive the response as plain JSON data by passing the
format parameter in the querystring like
Both methods are fine to try out a DRF API, but sometimes a command line tool is more handy as we can play more easily with the requests headers. You can use cURL, which is widely available on all major Linux/macOS distributions:
But usually I prefer to use HTTPie, which is a pretty awesome Python command line tool:
Now let’s protect this API endpoint so we can implement the token authentication:
Try again to access the API endpoint:
And now we get an HTTP 403 Forbidden error. Now let’s implement the token authentication so we can access this endpoint.
Implementing the Token Authentication
We need to add two pieces of information in our settings.py module. First include rest_framework.authtoken to
INSTALLED_APPS and include the
Migrate the database to create the table that will store the authentication tokens:
Now we need a user account. Let’s just create one using the
manage.py command line utility:
The easiest way to generate a token, just for testing purpose, is using the command line utility again:
This piece of information, the random string
9054f7aa9305e012b3c2300408c3dfdf390fcddf is what we are going to use
next to authenticate.
But now that we have the
TokenAuthentication in place, let’s try to make another request to our
Notice how our API is now providing some extra information to the client on the required authentication method.
So finally, let’s use our token!
And that’s pretty much it. For now on, on all subsequent request you should include the header
Authorization: Token 9054f7aa9305e012b3c2300408c3dfdf390fcddf.
The formatting looks weird and usually it is a point of confusion on how to set this header. It will depend on the client and how to set the HTTP request header.
For example, if we were using cURL, the command would be something like this:
Or if it was a Python requests call:
Or if we were using Angular, you could implement an
HttpInterceptor and set a header:
User Requesting a Token
The DRF provide an endpoint for the users to request an authentication token using their username and password.
Include the following route to the urls.py module:
So now we have a brand new API endpoint, which is
/api-token-auth/. Let’s first inspect it:
It doesn’t handle GET requests. Basically it’s just a view to receive a POST request with username and password.
Let’s try again:
The response body is the token associated with this particular user. After this point you store this token and apply it to the future requests.
Then, again, the way you are going to make the POST request to the API depends on the language/framework you are using.
If this was an Angular client, you could store the token in the
localStorage, if this was a Desktop CLI application
you could store in a text file in the user’s home directory in a dot file.
Hopefully this tutorial provided some insights on how the token authentication works. I will try to follow up this tutorial providing some concrete examples of Angular applications, command line applications and Web clients as well.
It is important to note that the default Token implementation has some limitations such as only one token per user, no built-in way to set an expiry date to the token.
You can grab the code used in this tutorial at github.com/sibtc/drf-token-auth-example.