8. Authentication
- Tell apart the three schemes you will meet in almost every API: API key, Bearer token, OAuth2.
- Use the
Authorizationheader correctly and recognize the 401s that come from a wrong header. - Keep secrets out of the code: environment variables and
.envfiles. - Know what NOT to do (tokens in URLs, in logs, in repositories).
Theory
Section titled “Theory”Authentication ≠ authorization
Section titled “Authentication ≠ authorization”- Authentication: who you are. It fails with 401.
- Authorization: what you may do. It fails with 403.
On our server the sandbox token is the authentication (it identifies your copy of the database); the 403 sql_not_allowed of POST /sql (chapter 12) is a denied authorization: you are recognized, but that operation is not allowed to anyone.
Three schemes
Section titled “Three schemes”| Scheme | How it is sent | Who uses it | Notes |
|---|---|---|---|
| API key | a proprietary header (X-API-Key: …) or, worse, the query string (?api_key=…) |
simple services, weather data, maps | a fixed string, often tied to the account; rotating it = changing it everywhere |
| Bearer token | Authorization: Bearer <token> (RFC 6750) |
almost every modern API | “bearer” = whoever carries it is authorized. It often expires. It can be opaque (like our sb_…) or a JWT (three base64 parts separated by dots, holding who you are and until when it is valid) |
| OAuth2 | you obtain a Bearer token through a flow (redirect to the provider, consent, exchange of a code) | “Sign in with Google”, Slack/GitHub/Microsoft APIs on behalf of a user | complex to set up, but in the end you always send Authorization: Bearer |
| HTTP Basic | Authorization: Basic base64(user:password) (curl’s -u) |
old APIs, internal services | only over HTTPS: base64 encoding is not encryption |
The course sandbox uses Bearer (and alternatively accepts X-Sandbox-Token, in API-key style, to show you both forms).
The Authorization header
Section titled “The Authorization header”Format: Authorization: <scheme> <credentials>. The scheme is a word (Bearer, Basic), then one space, then the value. Classic mistakes: wrong scheme (Token abc), missing scheme (Authorization: sb_…), expired token, a token copied with an extra space or newline.
Where to keep secrets
Section titled “Where to keep secrets”A token in the source code ends up in git, in backups, in screenshots. The rule:
- The secret lives in an environment variable (
export TOKEN=…) or in a.envfile listed in.gitignore. - The code reads it (
os.environ,process.env) and that is all. - The repository gets a
.env.examplewith the variable names and fake values. - Never in the URL (it ends up in server logs and in browser history), never in
print/console.log.
curl, explained
Section titled “curl, explained”With and without a token
Section titled “With and without a token”curl -sS -w ' → %{http_code}\n' https://corso-api-json.giuseppebosi.com/api/v1/sandbox/mecurl -sS -w ' → %{http_code}\n' -H "Authorization: Bearer $TOKEN" https://corso-api-json.giuseppebosi.com/api/v1/sandbox/mecurl -sS -w ' → %{http_code}\n' -H "X-Sandbox-Token: $TOKEN" https://corso-api-json.giuseppebosi.com/api/v1/sandbox/me- /sandbox/me
- "who am I?": the endpoint for checking a token. Many APIs have one (
/me,/user,/whoami) - (no header)
- → 401
unauthorized - -H "Authorization: Bearer $TOKEN"
- Bearer scheme: the standard
- -H "X-Sandbox-Token: $TOKEN"
- API-key style: a proprietary header, same effect on this server
{"error":{"code":"unauthorized","message":"Nessun token: aggiungi Authorization: Bearer <token>"}} → 401{"authenticated":true,"token_prefix":"sb_7cyEm…","expires_at":"2026-09-19T02:03:39Z"} → 200{"authenticated":true,"token_prefix":"sb_7cyEm…","expires_at":"2026-09-19T02:03:39Z"} → 200Note that the response shows only a prefix of the token: a well-built API never sends you the whole secret back.
401s “caused by the header”
Section titled “401s “caused by the header””curl -sS -H "Authorization: Token $TOKEN" https://corso-api-json.giuseppebosi.com/api/v1/sandbox/me; echocurl -sS -H "Authorization: Bearer sb_finto" https://corso-api-json.giuseppebosi.com/api/v1/sandbox/me; echocurl -sS -H 'Authorization: Bearer $TOKEN' https://corso-api-json.giuseppebosi.com/api/v1/sandbox/me; echo- "Authorization: Token …"
- wrong scheme →
bad_authorization: the server tells you the expected format - "Bearer sb_finto"
- right scheme, nonexistent (or expired) token →
invalid_token - 'Authorization: Bearer $TOKEN'
- single quotes: the shell does not expand
$TOKENand sends the six characters$TOKENliterally →invalid_token. The most common mistake of all - ; echo
- adds a newline between one output and the next (JSON responses do not end with a newline)
{"error":{"code":"bad_authorization","message":"Usa l'intestazione: Authorization: Bearer <token>"}}{"error":{"code":"invalid_token","message":"Token sandbox sconosciuto o scaduto: creane uno con POST /api/v1/sandbox"}}{"error":{"code":"invalid_token","message":"Token sandbox sconosciuto o scaduto: creane uno con POST /api/v1/sandbox"}}The token in a .env file
Section titled “The token in a .env file”# .env (aggiungilo a .gitignore!)CORSO_TOKEN=sb_7cyEmMkco216unjxIBct6XTQset -a; . ./.env; set +acurl -sS -H "Authorization: Bearer $CORSO_TOKEN" https://corso-api-json.giuseppebosi.com/api/v1/sandbox/me- set -a
- from now on every variable assigned is exported (visible to child processes, such as curl)
- . ./.env
- runs the file in the current shell (
.=source): theNAME=valuelines become variables - set +a
- turns auto-export off
- $CORSO_TOKEN
- now available, without the token appearing in the command or in the history
Python and TypeScript
Section titled “Python and TypeScript”Reading the token from an environment variable (falling back to a .env file), setting it once on the client, and a clear message if it is missing.
# CORSO_TOKEN=sb_… python3 auth.py (oppure: pip install python-dotenv e usa load_dotenv())import os, sysimport httpx
token = os.environ.get("CORSO_TOKEN")if not token: sys.exit("Imposta CORSO_TOKEN (ottienilo con: curl -sS -X POST …/api/v1/sandbox)")
client = httpx.Client( base_url="https://corso-api-json.giuseppebosi.com/api/v1", headers={"Authorization": f"Bearer {token}"}, # su ogni richiesta del client)r = client.get("/sandbox/me")if r.status_code == 401: sys.exit(f"token rifiutato: {r.json()['error']['code']}")print("autenticato fino a", r.json()["expires_at"])What you should see:
autenticato fino a 2026-11-02T20:53:01Z// CORSO_TOKEN=sb_… node --experimental-strip-types auth.ts (Node 20+: anche node --env-file=.env auth.ts)const token = process.env.CORSO_TOKEN;if (!token) { console.error("Imposta CORSO_TOKEN (ottienilo con: curl -sS -X POST …/api/v1/sandbox)"); process.exit(1); }
const base = "https://corso-api-json.giuseppebosi.com/api/v1";const headers = { Authorization: `Bearer ${token}` }; // riusato su ogni fetch
const r = await fetch(base + "/sandbox/me", { headers });if (r.status === 401) { console.error("token rifiutato:", (await r.json()).error.code); process.exit(1); }console.log("autenticato fino a", (await r.json()).expires_at);What you should see:
autenticato fino a 2026-11-02T20:55:53Znode --env-file=.env script.ts loads the .env file without any library (Node ≥ 20.6).
Try it now
Section titled “Try it now”Response headers
Response headers
Response headers
Exercise
Section titled “Exercise”Try it online, nothing to install:
The GET request straight in your browser: https://corso-api-json.giuseppebosi.com/api/v1/sandbox/me
Python on Google Colab (a free Google account is needed to run the cells); TypeScript on StackBlitz (it opens and starts by itself in the browser). If the practice API is switched off, turn it on from /en/api-attiva/.
- What is the practical difference between a 401 and a 403 for your code? What makes sense to retry?
- Write the
auth.py/auth.tsscript so that, ifCORSO_TOKENis missing or is rejected, it creates a new sandbox, prints the token only once (so you can copy it into.env) and carries on. - Why is
?token=sb_…in the query string a bad idea even though this server accepts it?
Solution
- 401 → a credentials problem: renew/get the token and retry once. 403 → the operation is forbidden: retrying is useless; change the request or ask for permissions.
- On
401callPOST /sandbox, update the client’s header with the new token and repeat theGET /sandbox/me. Print the token with a notice (“copy it into .env”), not on every run. - The URL ends up in the logs of the server and of the proxy, in the browser history, and in the
Refererheader if the page loads external resources. Headers do not. The server accepts it only for convenience in the course widgets.
Common mistakes
Section titled “Common mistakes”'Bearer $TOKEN'in single quotes in curl (said before, and you will see people do it for years).Authorization: sb_…without theBearerscheme.- A token in the repository: add
.envto.gitignorebefore the first commit; a committed secret must be rotated, deleting it from history is not enough. - Logging the request headers for debugging: mask
Authorization. - Mistaking a 401 for “I do not have permission”: it means “I do not know who you are”.
Summary
Section titled “Summary”Authorization: Bearer <token> (or an API-key header), 401 = who are you?, 403 = you may not. Secrets live in environment variables and .env, not in the code. Next chapter: searching by text, and why LIKE is not enough.