Authenticating to V6 API

The Pi-hole API v6.0 is completely rewritten and is now organized around REST.

The entire API is documented at http://pi.hole/api/docs and self-hosted by your Pi-hole to be 100% the API you see with your version. Using this locally served API documentation is preferred. In case you don't have v6.0 installed yet, you can also check out the documentation for all branches online, e.g., Pi-hole API documentation (development-v6).

The concept of gaining access to all resources by using a static token is too insecure going forward. The new API will instead give you a temporarily valid session ID (SID) after you logged in at POST /api/auth with a payload like {"password":"whatever-your-password-is"}.

This endpoint will return an SID you will from this point on send in your requests. Whether you do this via a Header, in the payload itself or in the request URI is up to you. It can even be provided by a cookie but this needs extra work (CSRF token in the header) to prevent a certain kind of identify theft attack the Pi-hole API is immune against.

The validity of the SID is prolonged on every request, and, otherwise, can also be set via a config option.

And in case you don't want to put your password on your scripts, you can also generate an application password that can be used in the same place as your regular password (and works even when 2FA is enabled for the regular password).

Summary: Everything is still pretty simple, you will have to get a token once by login in but then everything works simply with this (SID) token.

2 Likes