Skip to content

Add clarification to API behavior with respect to CSRF and cookies #1323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
manedurphy wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Add clarification to API behavior with respect to CSRF and cookies #1323

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1776b22
Add clarification to API behavior with respect to CSRF and cookies
manedurphy Dec 2, 2025
5480a86
Consistently parse JSON output in JavaScript examples
manedurphy Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 18 additions & 11 deletions docs/api/auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,12 @@ To get a session ID, you will have to send a `POST` request to the `/api/auth` e

xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
console.log(JSON.parse(this.responseText));
}
});

xhr.open("POST", "https://pi.hole/api/auth");
xhr.send(data);
```

=== "JavaScript (jQuery)"
Expand Down Expand Up @@ -138,7 +141,7 @@ Once you have a valid SID, you can use it to authenticate your requests. You can
3. In the `X-FTL-SID` header: `X-FTL-SID: vFA+EP4MQ5JJvJg+3Q2Jnw=`
4. In the `sid` cookie: `Cookie: sid=vFA+EP4MQ5JJvJg+3Q2Jnw=`

Note that when using cookie-based authentication, you will also need to send a `X-FTL-CSRF` header with the CSRF token that was returned when you authenticated. This is to prevent a certain kind of identity theft attack the Pi-hole API is immune against.
> Note that when using cookie-based authentication, you will also need to send a `X-CSRF-TOKEN` header with the CSRF token that was returned when you authenticated. This is to prevent a certain kind of identity theft attack the Pi-hole API is immune against. Also note that the API checks for a session ID in the cookie header before checking the request URI. Setting the session ID in the request URI is meaningless in cases where the browser automatically sets the session ID in the cookie header.

???+ example "Authentication with SID"

Expand All @@ -159,7 +162,6 @@ Note that when using cookie-based authentication, you will also need to send a `
payload = {}
headers = {
"X-FTL-SID": "vFA+EP4MQ5JJvJg+3Q2Jnw=",
"X-FTL-CSRF": "Ux87YTIiMOf/GKCefVIOMw="
}

response = requests.request("GET", url, headers=headers, data=payload, verify=False)
Expand All @@ -175,12 +177,13 @@ Note that when using cookie-based authentication, you will also need to send a `

xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
console.log(JSON.parse(this.responseText));
}
});

xhr.open("GET", "https://pi.hole/api/dns/blocking?sid=vFA+EP4MQ5JJvJg+3Q2Jnw=");
xhr.setRequestHeader("X-FTL-CSRF", "Ux87YTIiMOf/GKCefVIOMw=");
// The browser sets the "Cookie: sid=vFA+EP4MQ5JJvJg+3Q2Jnw=" header automatically
xhr.open("GET", "https://pi.hole/api/dns/blocking");
xhr.setRequestHeader("X-CSRF-TOKEN", "Ux87YTIiMOf/GKCefVIOMw=");
xhr.send(data);
```

Expand All @@ -195,7 +198,6 @@ Note that when using cookie-based authentication, you will also need to send a `
contentType: "application/json",
headers: {
"X-FTL-SID": "vFA+EP4MQ5JJvJg+3Q2Jnw=",
"X-FTL-CSRF": "Ux87YTIiMOf/GKCefVIOMw="
}
}).done(function(data) {
console.log(data);
Expand All @@ -210,7 +212,7 @@ Note that when using cookie-based authentication, you will also need to send a `

**Headers**

If you use cookie-based authentication, you will also need to send a `X-FTL-CSRF` header with the CSRF token that was returned when you authenticated.
If you use cookie-based authentication, you will also need to send a `X-CSRF-TOKEN` header with the CSRF token that was returned when you authenticated.

## Authentication with 2FA

Expand Down Expand Up @@ -248,9 +250,12 @@ If you have 2FA enabled for your Pi-hole, you will need to provide a TOTP token

xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
console.log(JSON.parse(this.responseText));
}
});

xhr.open("POST", "https://pi.hole/api/auth");
xhr.send(data);
```

=== "JavaScript (jQuery)"
Expand Down Expand Up @@ -355,11 +360,13 @@ To end your session before the SID expires, you can send a `DELETE` request to t

xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
console.log(JSON.parse(this.responseText));
}
});

xhr.open("DELETE", "https://pi.hole/api/auth?sid=vFA+EP4MQ5JJvJg+3Q2Jnw=");
// The browser sets the "Cookie: sid=vFA+EP4MQ5JJvJg+3Q2Jnw=" header automatically
xhr.open("DELETE", "https://pi.hole/api/auth");
xhr.setRequestHeader("X-CSRF-TOKEN", "Ux87YTIiMOf/GKCefVIOMw=");
xhr.send(data);
```

Expand Down