APIs with FastAPI · Chapter 14 of 26
Permissions
By the end of this chapter you can tell "who are you?" from "may you do this?" in every route: answer 401 and 403 for the right reasons, write a role check once and reuse it, make sure a merchant only ever touches its own parcels, let staff see everything, and accept API keys from machines and tokens from people on the same route. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Security and real-world behaviour
- 4 tasks
- FastAPI
- In the all labs plan
The first 2 chapters of APIs with FastAPI are free. This one comes with the all labs plan.
Why you need this
Since chapter 13 every person who uses DakiyaGo has a token, and every token has a role in it: merchant, rider or staff. Sunita read the code and found the problem at once: any valid token works on every route. Pooja, a rider, can read the daily report. Neelkanth Blue Pottery can read Gulabi Block Prints' parcels, with their customers' addresses and cash amounts, just by changing the AWB in the URL.
A token answers who is asking. It says nothing about what they may do. That second question has to be asked in every route, the same way every time, and the answer must not leak what the caller is not allowed to know.
What you build: 4 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
roles.py: who may do what
Every token now carries a role: merchant, rider or staff. Make an app with three routes: GET /hubs for any signed-in role (the hubs from /workspace/data/hubs.json), GET /hubs/{code}/riders for riders and staff (that hub's riders from riders.json, in the file's order), and GET /riders for staff only (every rider).
No token or a bad token answers 401 (current_user in the starter does that). A signed-in user whose role is not allowed, including a role nobody expected, answers 403. Write the role check once, as a dependency each route asks for with the roles it allows.
- Task 2
keys.py: keys for machines, tokens for people
Shop software sends its merchant's API key in the header X-Api-Key (merchants.json has every merchant's test key); people send Authorization: Bearer <token>, where the token's role is merchant and its sub is the merchant id. Make an app with GET /parcels that answers the asking merchant's parcels from /workspace/data/parcels.json, smallest AWB first, for either.
No key and no token answers 401, a key nobody has answers 401, a bad token answers 401, and a good token whose role is not merchant answers 403. Write one dependency that answers the merchant id from whichever came; decode tokens with SECRET (in the starter) and HS256.
- Task 3
ownership.py: your parcels, and only yours
Make an app over /workspace/data/parcels.json with GET /parcels/{awb} and GET /parcels. A merchant gets its own parcel; someone else's parcel answers 404, character for character the same as a parcel that does not exist. Staff get any parcel. GET /parcels answers a merchant's own parcels, or for staff all of them (or one merchant's with ?merchant_id=M05); a merchant asking for another merchant_id answers 403. Lists are smallest AWB first.
Riders answer 403 on both routes, and no token answers 401. The check signs in as M01, M02, a rider and staff.
- Task 4 · interview question
Interview: cancel.py, cancel but not someone else's
A developer at Marwar Spices (M03) is trying AWBs one after another on the cancel route. Make an app over /workspace/data/parcels.json, kept in memory, with POST /parcels/{awb}/cancel. A merchant's own booked parcel becomes cancelled and the answer is {"awb": ..., "status": "cancelled"}; its own parcel that is not booked answers 409. Someone else's parcel, whatever its status, answers 404, identical to a parcel that does not exist, and does not change. Staff may cancel any booked parcel; riders answer 403 and no token 401.
The check has M03 try M05's booked DKG10020, then M05 cancel it, and M01 try M02's picked-up DKG10027. The interviewer will ask why someone else's parcel answers 404 and not 403.
What you will learn
- Authentication versus authorisation, and 401 versus 403.
- A role check as a dependency, written once and given the roles.
- Ownership: a merchant sees only its own rows, and why someone else's row answers 404.
- Staff overrides: the same route, more rows for a wider role.
- API keys for machines, tokens for people, on one route.
More in Security and real-world behaviour
Build "Permissions" yourself
DakiyaGo, a Jaipur courier startup, takes bookings on WhatsApp. Merchants want an API, and you build it. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
The first 2 chapters of APIs with FastAPI are free. This one comes with the all labs plan.