Tutorial part 3: authentication and permissions¶
At the end of part 2, any client can change any article. In this part, you add these rules:
- A client gets a token with a username and a password.
- Only a client with a token can create, change or delete an article.
- The author of a new article is the user of the token.
- Only the author of an article can change or delete it.
Bolt uses JSON Web Tokens (JWT) here.
It signs and checks them with the SECRET_KEY of Django.
Create a second user¶
You need two users to test the last rule. Create bob in the Django shell:
>>> from django.contrib.auth.models import User
>>> User.objects.create_user("bob", password="battery-staple")
<User: bob>
>>> exit()
bob has the ID 2.
Issue a token¶
Replace the contents of mysite/api.py:
import msgspec
from django.contrib.auth import aauthenticate
from django_bolt import BoltAPI
from django_bolt.auth import create_jwt_for_user
from django_bolt.exceptions import Unauthorized
api = BoltAPI()
class Credentials(msgspec.Struct):
username: str
password: str
class Token(msgspec.Struct):
access_token: str
token_type: str = "bearer"
@api.get("/hello")
async def hello() -> dict:
return {"message": "Hello from Django-Bolt"}
@api.post("/token")
async def issue_token(credentials: Credentials) -> Token:
user = await aauthenticate(username=credentials.username, password=credentials.password)
if user is None:
raise Unauthorized(detail="Invalid username or password")
return Token(access_token=create_jwt_for_user(user))
The /token route reads a username and a password from the JSON body.
aauthenticate() is the async form of Django's authenticate(). It checks the password with the authentication backends of Django.
create_jwt_for_user() makes a token for the user. The token is valid for one hour.
If the password is wrong, the handler raises Unauthorized, and Bolt sends a 401 response.
Send a wrong password:
curl -i -X POST localhost:8000/token \
-H "Content-Type: application/json" \
-d '{"username": "alice", "password": "wrong"}'
HTTP/1.1 401 Unauthorized
content-length: 41
content-type: application/json
{"detail":"Invalid username or password"}
Send the correct password:
curl -X POST localhost:8000/token \
-H "Content-Type: application/json" \
-d '{"username": "alice", "password": "correct-horse"}'
{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwiZXhwIjoxNzk1MzE3MTU5LCJpYXQiOjE3OTUzMTM1NTksImlzX3N0YWZmIjpmYWxzZSwiaXNfc3VwZXJ1c2VyIjpmYWxzZSwidXNlcm5hbWUiOiJhbGljZSJ9.X3ccn4WNn474-KJSoejB4dhxQg-3Ge4TCaEeXXGjybE","token_type":"bearer"}
Your token is different. Keep a token for each user in a shell variable:
ALICE_TOKEN=$(curl -s -X POST localhost:8000/token \
-H "Content-Type: application/json" \
-d '{"username": "alice", "password": "correct-horse"}' \
| python -c "import json, sys; print(json.load(sys.stdin)['access_token'])")
BOB_TOKEN=$(curl -s -X POST localhost:8000/token \
-H "Content-Type: application/json" \
-d '{"username": "bob", "password": "battery-staple"}' \
| python -c "import json, sys; print(json.load(sys.stdin)['access_token'])")
Protect the write routes¶
Replace the contents of articles/api.py:
from datetime import datetime
from typing import Annotated
import msgspec
from django.contrib.auth.models import User
from django_bolt import BoltAPI, CurrentUser
from django_bolt.auth import IsAuthenticated, JWTAuthentication
from django_bolt.exceptions import Forbidden, NotFound
from .models import Article
api = BoltAPI()
class ArticleIn(msgspec.Struct):
title: Annotated[str, msgspec.Meta(min_length=1, max_length=200)]
body: str
published: bool = False
class ArticleOut(msgspec.Struct):
id: int
title: str
body: str
author_id: int
published: bool
created_at: datetime
@api.get("/articles")
async def list_articles(published: bool | None = None, search: str = "") -> list[ArticleOut]:
articles = Article.objects.all()
if published is not None:
articles = articles.filter(published=published)
if search:
articles = articles.filter(title__icontains=search)
return articles
@api.post(
"/articles",
status_code=201,
auth=[JWTAuthentication()],
guards=[IsAuthenticated()],
)
async def create_article(data: ArticleIn, user: CurrentUser) -> ArticleOut:
return await Article.objects.acreate(
title=data.title,
body=data.body,
author=user,
published=data.published,
)
async def get_article(article_id: int) -> Article:
try:
return await Article.objects.aget(id=article_id)
except Article.DoesNotExist:
raise NotFound(detail=f"Article {article_id} not found") from None
async def get_own_article(article_id: int, user: User) -> Article:
article = await get_article(article_id)
if article.author_id != user.id:
raise Forbidden(detail="You can only change your own articles")
return article
@api.get("/articles/{article_id}")
async def get_article_detail(article_id: int) -> ArticleOut:
return await get_article(article_id)
@api.put(
"/articles/{article_id}",
auth=[JWTAuthentication()],
guards=[IsAuthenticated()],
)
async def update_article(article_id: int, data: ArticleIn, user: CurrentUser) -> ArticleOut:
article = await get_own_article(article_id, user)
article.title = data.title
article.body = data.body
article.published = data.published
await article.asave()
return article
@api.delete(
"/articles/{article_id}",
status_code=204,
auth=[JWTAuthentication()],
guards=[IsAuthenticated()],
)
async def delete_article(article_id: int, user: CurrentUser) -> None:
article = await get_own_article(article_id, user)
await article.adelete()
These are the changes from part 2:
ArticleInhas noauthor_idfield. The client cannot choose the author.- The
POST,PUTandDELETEroutes haveauthandguardsarguments. - These handlers have a
user: CurrentUserparameter. get_own_articleraisesForbiddenwhen the user is not the author.
Require a token¶
auth=[JWTAuthentication()] tells Bolt to read a token from the Authorization: Bearer <token> header.
Bolt checks the signature and the expiry time of the token in Rust, before it calls Python.
guards=[IsAuthenticated()] rejects a request that has no valid token. Bolt sends 401, and the handler does not run.
A guard checks the request before the handler. For other guards, see Permissions.
The GET routes have no auth argument. They stay public.
Set the author¶
CurrentUser is a dependency. It loads the User of the token from the database, and gives it to the handler.
create_article uses this user as the author.
Allow only the author to change an article¶
A guard can check the data in the token, for example a role or a permission.
It cannot check the author of an article, because that data is in the database.
Thus update_article and delete_article call get_own_article. It loads the article, compares the author with the user, and raises Forbidden (403) for a different user.
Try the rules¶
Create an article with no token:
curl -i -X POST localhost:8000/articles \
-H "Content-Type: application/json" \
-d '{"title": "Signed article", "body": "Written by Alice."}'
HTTP/1.1 401 Unauthorized
content-length: 36
www-authenticate: Bearer
content-type: application/json
{"detail":"Authentication required"}
A token that is not valid gets the same response:
curl -i -X POST localhost:8000/articles \
-H "Authorization: Bearer not-a-token" \
-H "Content-Type: application/json" \
-d '{"title": "Forged", "body": "Bad token."}'
HTTP/1.1 401 Unauthorized
content-length: 36
www-authenticate: Bearer
content-type: application/json
{"detail":"Authentication required"}
Create an article as alice:
curl -i -X POST localhost:8000/articles \
-H "Authorization: Bearer $ALICE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "Signed article", "body": "Written by Alice.", "published": true}'
HTTP/1.1 201 Created
content-length: 134
content-type: application/json
{"id":3,"title":"Signed article","body":"Written by Alice.","author_id":1,"published":true,"created_at":"2026-11-22T02:12:40.524136Z"}
The body has no author_id, and the response has "author_id":1. Bolt took the author from the token.
Change the article as bob:
curl -i -X PUT localhost:8000/articles/3 \
-H "Authorization: Bearer $BOB_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "Edited by Bob", "body": "Bob was here."}'
HTTP/1.1 403 Forbidden
content-length: 50
content-type: application/json
{"detail":"You can only change your own articles"}
Change the article as alice:
curl -X PUT localhost:8000/articles/3 \
-H "Authorization: Bearer $ALICE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "Signed article", "body": "Edited by Alice.", "published": true}'
{"id":3,"title":"Signed article","body":"Edited by Alice.","author_id":1,"published":true,"created_at":"2026-11-22T02:12:40.524136Z"}
Delete the article as bob:
HTTP/1.1 403 Forbidden
content-length: 50
content-type: application/json
{"detail":"You can only change your own articles"}
The list is still public:
[{"id":3,"title":"Signed article","body":"Edited by Alice.","author_id":1,"published":true,"created_at":"2026-11-22T02:12:40.524136Z"},{"id":1,"title":"Hello, Bolt","body":"My first article.","author_id":1,"published":true,"created_at":"2026-11-22T02:12:35.217932Z"}]
Use the token in the API docs¶
Open http://127.0.0.1:8000/docs.
The POST, PUT and DELETE routes now show a lock icon.
- Click Authorize.
- Paste the value of
$ALICE_TOKEN(runecho $ALICE_TOKEN), and click Authorize. - Send a request from a protected route with Try it out.
Swagger UI adds the Authorization header to each request.
Summary¶
create_jwt_for_user()makes a token.JWTAuthenticationchecks it.- A guard such as
IsAuthenticated()rejects a request before the handler runs. CurrentUsergives the user of the token to the handler.- A rule that needs the database, such as "only the author", goes in the handler or in a dependency.
Next: Part 4: tests and running in production
See also¶
- Authentication: JWT options, API keys, sessions and token refresh.
- Permissions:
IsAuthenticated,AllowAnyandRequires. - Dependencies: reuse code such as
get_own_articlewithDepends.