🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

🪪 धडा 06 — Auth: काउंटरवरचे हॉल पास

📍 तुम्ही इथे आहात: 12 पैकी धडा 06 · मागे: lesson-05-build-an-api · पुढे: lesson-07-errors-idempotency

📦 या ब्रँचमध्ये काय आहे

धडे 01–05, आणि त्यासोबत कोणत्या slips कोण देऊ शकतो: API keys, bearer tokens / JWTs, OAuth, आणि एकसारखे नसलेले दोन नकार (401 विरुद्ध 403).

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

सूचना फलक वाचायला pass लागत नाही — कोणीही GET करू शकतो. पण नोंदवहीत लिहायचे (POST, PUT, DELETE) तर counter वर हॉल पास 🪪 दाखवावा लागतो. आमचा counter आज एकाच प्रकारचा pass स्वीकारतो: एक header, X-API-Key: hall-pass-123.

Pass अजिबात नाही → 401 unauthenticated: "तुम्ही कोण?"
Pass आहे, पण लिहिण्याची परवानगी असलेला नाही → 403 forbidden: "तुम्ही कोण ते मला माहीत आहे; तुम्हाला परवानगी नाही."

खऱ्या शाळा तीन प्रकारचे pass देतात, आणि तुम्हाला तिन्ही भेटतील:

API key 🔑 — एका program ला (canteen app) दिलेली लांब random string. सोपी, दीर्घकाळ टिकणारी, रद्द करता येणारी. ती कधीच URL, log, किंवा browser मध्ये ठेवू नका — JavaScript मध्ये ship होताक्षणी ती सार्वजनिक होते.
Bearer token / JWT 🎫 — व्यक्तीने login केल्यानंतर तिला दिलेला सही केलेला, मुदत संपणारा pass: Authorization: Bearer eyJ…. Server तो शोधण्याऐवजी सही तपासतो; मुदत संपली की तो आपोआप चालायचा बंद होतो.
OAuth 2 / OIDC 🤝 — अधिकार सोपवण्याचा खेळ: "हे calendar app माझे events वाचू शकते, पण delete करू शकत नाही", user ने provider च्या पानावर दिलेली, मर्यादित (scoped), रद्द करता येणारी परवानगी. CI/CD आणि AWS schools मधला OIDC badge हाच protocol machines मध्ये वापरलेला आहे.

Pass कोणताही असो, नियम आहे least privilege: प्रत्येक app ला एक key, त्याला जेवढे करायचे तेवढ्यापुरती मर्यादित, ठरलेल्या वेळापत्रकाने बदललेली (rotate), आणि उघड झाली त्याच दिवशी रद्द केलेली.

🗺️ आकृती

flowchart LR
    r["🔓 GET (read)"] -->|"1 no pass needed"| ok1["200"]
    w["✍️ POST / PUT / DELETE"] -->|"2 X-API-Key?"| chk{"pass?"}
    chk -->|"none"| u["401 unauthenticated"]
    chk -->|"wrong"| f["403 forbidden"]
    chk -->|"right"| ok2["201 / 200 / 204"]
    subgraph kinds["🪪 three kinds of pass"]
        k["🔑 API key — a program's"]
        t["🎫 bearer token / JWT — a person's, expires"]
        o["🤝 OAuth / OIDC — delegated, scoped"]
    end

❓ काय

Authentication = कोण विचारत आहे (pass). Authorization = त्यांना काय करण्याची परवानगी आहे (scope). 401 म्हणजे authentication मधले अपयश, 403 authorization मधले — त्यांची अदलाबदल कधीच करू नका.
API keys header मधून जातात (X-API-Key किंवा Authorization: ApiKey), query string मधून कधीच नाही (URLs logs आणि browser history मध्ये पोहोचतात). Server वर फक्त hash ठेवा; key तयार करताना एकदाच दाखवा.
JWT: header.payload.signature, base64. Payload वाचता येतो (गुप्त नाही!) — sub, exp, scope. सही सांगते की तो कोणी दिला. कमी मुदत + refresh tokens ही प्रमाणित पद्धत आहे.
OAuth 2: user च्या वतीने काम करणाऱ्या apps साठी authorization code flow; machine-to-machine साठी client credentials; scopes परवानग्यांची नावे सांगतात. OIDC त्यावर "हा user कोण" याची भर घालते.
Transport: TLS (https://) शिवाय हे सगळे निरुपयोगी आहे — मैदानावर ओरडून सांगितलेला pass म्हणजे pass नाही.

🪪 प्रत्येक प्रकारचा हॉल पास: हा धडा API key वापरतो. Basic, Bearer tokens, JWT, session cookies, PKCE सह OAuth 2.0, OpenID Connect, HMAC request signing आणि mutual TLS प्रत्येकाचे चित्र काढलेले आहे — प्रत्येक OAuth grant type, 401 विरुद्ध 403, निर्णय-मार्गदर्शन आणि चुका यांसह — धडा 14 — प्रत्येक authentication पद्धत मध्ये. त्यातल्या सात इथे चालतात (grant_type=password नाकारणाऱ्या OAuth token endpoint सह): python3 api/auth_demo.py मग python3 api/auth_client.py तारेवरचा प्रत्येक header, मुदत संपलेला token, बनावट JWT, छेडछाड केलेली सही आणि पुन्हा पाठवलेली (replayed) request दाखवते.

🤔 का

कारण counter हीच एकमेव जागा आहे जिथे slip आणि pass दोन्ही दिसतात. तपासणी इतर कुठेही ठेवा — UI मध्ये, database मध्ये — आणि कोणीतरी ती टाळणारे दार शोधेलच. आणि 401/403 मधला गोंधळ म्हणजे फक्त पांडित्य नाही: 401 वर clients पुन्हा login करतात आणि 403 वर थांबतात; त्यांची अदलाबदल केली तर users कायम फेऱ्यात अडकतात किंवा चुकीने हार मानतात.

🔧 कसे (या repo मध्ये)

school_api.py मधले authorized(): header नाही → 401, चुकीची किंमत → 403. Key environment मधल्या SCHOOL_API_KEY मधून येते. प्रत्येक write handler ते route तपासणीच्या नंतर आणि body वाचण्याच्या आधी call करतो — धडा 05 मधला क्रम.

🧪 करून पाहा

B=http://127.0.0.1:8080/v1; J='Content-Type: application/json'
curl -s -X POST $B/students -H "$J" -d '{"name":"Zoya","class":"3B"}'                              # 401
curl -s -X POST $B/students -H 'X-API-Key: wrong' -H "$J" -d '{"name":"Zoya","class":"3B"}'        # 403
curl -s -X POST $B/students -H 'X-API-Key: hall-pass-123' -H "$J" -d '{"name":"Zoya","class":"3B"}' # 201
# rotate the pass without touching code:
SCHOOL_API_KEY=new-pass-456 python3 api/school_api.py 8081 &
curl -s -X DELETE http://127.0.0.1:8081/v1/students/1 -H 'X-API-Key: hall-pass-123' -o /dev/null -w '%{http_code}\n'   # 403 — old pass

✅ तपासा — तुम्हाला काय दिसायला हवे

hint: the hall pass is missing सह 401, मग a pass, but not the right one सह 403, मग 201. Port 8081 वर जुन्या key ला 403 मिळतो — तुम्ही environment variable ने आणि code मध्ये शून्य बदल करून credential rotate केले.

🏁 तुम्ही आत्ताच काय सिद्ध केले

वाचण्याची आणि लिहिण्याची दारे वेगळी आहेत, दोन नकारांचे अर्थ वेगळे आहेत, आणि pass code च्या बाहेर राहतो.

⚠️ नेहमीच्या चुका

pass नसताना 403 (किंवा चुकीच्या pass साठी 401) — दोन्ही बाबतीत clients चुकीचे वागतात
query strings मधल्या किंवा git मध्ये commit केलेल्या keys — असे घडले (आणि ते घडेलच) की लगेच rotate करा
browser app मध्ये API key — user token वापरा; key ship होताक्षणी सार्वजनिक होते
प्रत्येक app साठी एकच सर्वशक्तिमान key — प्रत्येक app ला एक key, मर्यादित, म्हणजे तुम्ही एकच वापरकर्ता रद्द करू शकता
जिथे pass प्रवास करतो तिथे TLS शिवाय HTTP

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: बहुतेक खरे API breaches हुशारीचे नसतात — public repo मधली key, कधीच मुदत न संपणारा token, किंवा authorized() call करायला विसरलेला endpoint. वरचे कंटाळवाणे नियम हेच संपूर्ण संरक्षण आहे.

⏭️ पुढे

भाग 2 सुरू होतो: counter खऱ्या जगात चालवणे. आधी, नम्र नकार आणि पावती क्रमांक — errors, retries आणि idempotency keys.

git checkout lesson-07-errors-idempotency

🪪 Lesson 06 — Auth: hall passes at the counter

📍 You are here: Lesson 06 of 12 · Previous: lesson-05-build-an-api · Next: lesson-07-errors-idempotency

📦 What's in this branch

Lessons 01–05, plus who may hand in which slips: API keys, bearer tokens / JWTs, OAuth, and the two refusals that are not the same thing (401 vs 403).

🧒 Explain like I'm 5

Reading the notice board needs no pass — anyone may GET. But writing in the register (POST, PUT, DELETE) means showing a hall pass 🪪 at the counter. Our counter accepts one kind today: a header, X-API-Key: hall-pass-123.

No pass at all → 401 unauthenticated: "who are you?"
A pass, but not one that may write → 403 forbidden: "I know who you are; you may not."

Real schools issue three kinds of pass, and you will meet all three:

API key 🔑 — a long random string given to a program (the canteen app). Simple, long-lived, revocable. Never put it in a URL, a log, or a browser — it is public the moment it ships in JavaScript.
Bearer token / JWT 🎫 — a signed, expiring pass issued to a person after they log in: Authorization: Bearer eyJ…. The server checks the signature instead of looking it up; it stops working by itself when it expires.
OAuth 2 / OIDC 🤝 — the delegation dance: "this calendar app may read my events, but not delete them", granted by the user on the provider's page, scoped, revocable. The CI/CD and AWS schools' OIDC badge is this same protocol used between machines.

Whatever the pass, the rule is least privilege: a key per app, scoped to what it must do, rotated on a schedule, revoked the day it leaks.

🗺️ Diagram

flowchart LR
    r["🔓 GET (read)"] -->|"1 no pass needed"| ok1["200"]
    w["✍️ POST / PUT / DELETE"] -->|"2 X-API-Key?"| chk{"pass?"}
    chk -->|"none"| u["401 unauthenticated"]
    chk -->|"wrong"| f["403 forbidden"]
    chk -->|"right"| ok2["201 / 200 / 204"]
    subgraph kinds["🪪 three kinds of pass"]
        k["🔑 API key — a program's"]
        t["🎫 bearer token / JWT — a person's, expires"]
        o["🤝 OAuth / OIDC — delegated, scoped"]
    end

❓ What

Authentication = who is asking (the pass). Authorization = what they may do (the scope). 401 is an authentication failure, 403 an authorization one — never swap them.
API keys travel in a header (X-API-Key or Authorization: ApiKey), never in the query string (URLs end up in logs and browser history). Store only a hash server-side; show the key once at creation.
JWT: header.payload.signature, base64. The payload is readable (not secret!) — sub, exp, scope. The signature proves who issued it. Short expiry + refresh tokens is the standard pattern.
OAuth 2: authorization code flow for apps acting for a user; client credentials for machine-to-machine; scopes name the permissions. OIDC adds "who is this user" on top.
Transport: all of this is worthless without TLS (https://) — a pass shouted across the playground is not a pass.

🪪 Every kind of hall pass: this lesson uses an API key. Basic, Bearer tokens, JWT, session cookies, OAuth 2.0 with PKCE, OpenID Connect, HMAC request signing and mutual TLS are each drawn — with every OAuth grant type, 401 vs 403, a decision guide and the mistakes — in lesson 14 — every authentication method. Seven of them run here (including an OAuth token endpoint that refuses grant_type=password): python3 api/auth_demo.py then python3 api/auth_client.py shows every header on the wire, an expired token, a forged JWT, a tampered signature and a replayed request.

🤔 Why

Because the counter is the only place that sees both the slip and the pass. Put the check anywhere else — in the UI, in the database — and somebody will find the door that skips it. And because 401/403 confusion is not pedantry: clients re-login on 401 and stop on 403; swap them and users loop forever or give up wrongly.

🔧 How (in this repo)

authorized() in school_api.py: missing header → 401, wrong value → 403. The key comes from SCHOOL_API_KEY in the environment. Every write handler calls it after the route check and before reading the body — the order from lesson 05.

🧪 Try it

B=http://127.0.0.1:8080/v1; J='Content-Type: application/json'
curl -s -X POST $B/students -H "$J" -d '{"name":"Zoya","class":"3B"}'                              # 401
curl -s -X POST $B/students -H 'X-API-Key: wrong' -H "$J" -d '{"name":"Zoya","class":"3B"}'        # 403
curl -s -X POST $B/students -H 'X-API-Key: hall-pass-123' -H "$J" -d '{"name":"Zoya","class":"3B"}' # 201
# rotate the pass without touching code:
SCHOOL_API_KEY=new-pass-456 python3 api/school_api.py 8081 &
curl -s -X DELETE http://127.0.0.1:8081/v1/students/1 -H 'X-API-Key: hall-pass-123' -o /dev/null -w '%{http_code}\n'   # 403 — old pass

✅ Verify — what you should see

401 with hint: the hall pass is missing, then 403 with a pass, but not the right one, then 201. On port 8081 the old key gets 403 — you rotated a credential with an environment variable and zero code changes.

🏁 What you just proved

Reads and writes have different doors, the two refusals mean different things, and the pass lives outside the code.

⚠️ Common mistakes

403 for a missing pass (or 401 for a wrong one) — clients behave wrongly on both
keys in query strings or committed to git — rotate immediately when it happens (it will)
an API key in a browser app — use a user token; the key is public the moment it ships
one god-key for every app — one key per app, scoped, so you can revoke one consumer
HTTP without TLS anywhere a pass travels

🏭 Why this matters in production: most real API breaches are not clever — they are a key in a public repo, a token that never expired, or an endpoint that forgot to call authorized(). The boring rules above are the whole defence.

⏭️ Next

Part 2 begins: running the counter for real. First, polite refusals and receipt numbers — errors, retries and idempotency keys.

git checkout lesson-07-errors-idempotency

← Previousbuild an api Next →errors idempotency

This page is the lesson's README from the lesson-06-auth branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.