Add clarification to API behavior with respect to CSRF and cookies

[manedurphy]

Thank you for your contribution to the Pi-hole Community!

Please read the comments below to help us consider your Pull Request.

We are all volunteers and completing the process outlined will help us review your commits quicker.

Please make sure you

1. Base your code and PRs against the repositories developmental branch.
2. Sign Off all commits as we enforce the DCO for all contributions
3. Sign all your commits as they must have verified signatures
4. File a pull request for any change that requires changes to our documentation at our documentation repo

---

What does this PR aim to accomplish?:

• Adds clarity on how the Pi-hole API validates requests with Cookie authentication and CSRF tokens.
• The docs mentions that cookie-based authentication must include a CSRF token in the X-FTL-CSRF header, but the code shows that the header is named X-CSRF-TOKEN, see here.
• The code examples show the use of the X-FTL-CSRF in scenarios where the code/script run outside of the browser. This is misleading, as those example do not explicitly opt-in for cookie-based authentication.
• A JavaScript example showed setting the sid value in the request URI in additional to setting the CSRF token, which is also misleading because in a browser we would expect the cookie to be set automatically, which the API checks before checking the request URI.

How does this PR accomplish the above?:

• All changes address the following points mentioned above

Link documentation PRs if any are needed to support this PR:

• N/A

---

By submitting this pull request, I confirm the following:

1. I have read and understood the contributors guide, as well as this entire template. I understand which branch to base my commits and Pull Requests against.
2. I have commented my proposed changes within the code and I have tested my changes.
3. I am willing to help maintain this change if there are issues with it later.
4. It is compatible with the EUPL 1.2 license
5. I have squashed any insignificant commits. (git rebase)
6. I have checked that another pull request for this purpose does not exist.
7. I have considered, and confirmed that this submission will be valuable to others.
8. I accept that this submission may not be used, and the pull request closed at the will of the maintainer.
9. I give this submission freely, and claim no ownership to its content.

---

• I have read the above and my PR is ready for review. Check this box to confirm

[netlify]

✅ Deploy Preview for pihole-docs ready!

Name	Link
🔨 Latest commit	a515ee8
🔍 Latest deploy log	https://app.netlify.com/projects/pihole-docs/deploys/6a65feb0ed558a0008f41288
😎 Deploy Preview	https://deploy-preview-1323--pihole-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[dschaper]

@DL6ER Can you check this over and see if it lines up with the API design please?

[DL6ER]

The header rename is correct. X-FTL-CSRF was a working title early in the webserver auth work and became X-CSRF-TOKEN before release - the docs just never followed. The code reads only X-CSRF-TOKEN (mg_get_header(api->conn, "X-CSRF-TOKEN"), src/api/auth.c), so the old name matched nothing.

The rest lines up with the code as well. CSRF is only checked for cookie-sourced SIDs (need_csrf = cookie_auth && is_api), so dropping X-FTL-CSRF from the X-FTL-SID (header-auth) examples is right - it did nothing there. And the SID precedence is indeed payload -> header -> cookie -> URI, so a browser holding the sid cookie takes the cookie path regardless of any ?sid=. The cookie is HttpOnly on top of that, i.e., JS cannot read the sid to put it in the URI in the first place, which you could add to strengthen that point.

One correction: the DELETE /api/auth example now sends X-CSRF-TOKEN, but that endpoint does not require it. /api/auth has require_auth = false and validates the session itself via check_client_auth(api, false), i.e., is_api = false, so need_csrf is always false there - login and logout work with a cookie and no CSRF token. That is deliberate: a forced logout is a nuisance at worst, and SameSite=Lax already keeps the cookie off any cross-site DELETE. So the header in that example is dead weight, the same thing this PR strips from the Python and jQuery examples. Please drop it from the DELETE example.

[DL6ER]

Please drop CSRF from the auth DELETE example. Thereafter, good to be merged. Sorry for the very long review, I simply missed the ping and found this by pure luck while skimming over old PRs.