Hello, I am familiar with the V5 API but need some help with the V6 API.
Is there any documentation on how I pass authentication credentials when using the new API ?
I am testing API functionality using Postman and need to know how to format the get request.
Thank you
Hope this helps.
Thanks but Iām trying to authenticate programmatically not manually.
Previously with the v5 api I would pass a token via the http request such as:
I am looking for the equivalent v6 syntax
Thanks.
Not sure the syntax has changed.
Have you tried the password hash as the token (which is in pihole.toml):
'### webserver.api.pwhash
API password hash
Value (string)
Allowed value: '
Or an app password for API access.
`### webserver.api.app_pwhash
Pi-hole application password.
After you turn on two-factor (2FA) verification and set up an Authenticator app, you may run into issues if you use apps or other services that don't support two-step verification. In this case, you can create and use an app password to sign in. An app password is a long, randomly generated password that can be used instead of your regular password + TOTP token when signing in to the API. The app password can be generated through the API and will be shown only once. You can revoke the app password at any time. If you revoke the app password, be sure to generate a new one and update your app with the new password.
Value (string)`
Or disable local authentication:
`### webserver.api.localAPIauth
Do local clients need to authenticate to access the API? This settings allows local clients to use the API without authentication.
Enabled`
Hi, previously if I issued the commend:
http://192.168.101.23/admin/api.php?topItems=10&auth=f13dedb16605499.......cce0be52a93
I got this response:
{
"top_queries": ,
"top_ads":
}
it's a new instance so no data yet but the json data returned is valid
Now if I try with the old token, or a hash of the current password, or an application password I get the following results:
<?xml version="1.0" encoding="iso-8859-1"?> 404 Not FoundIf I put in a random set of characters for the token I get the same results as above
I need to know how to make the base request with authentication then I can modify for the other API endpoints
Thanks,
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.
Wow, it is different. For @compiledbinary 's request, it looks to me something like:
curl -X GET "https://192.168.101.23:443/api/stats/database/top_clients?from=1672580025&until=1672666425&blocked=false&count=10" -H "accept: application/json" -H "sid: ABCdef123hssN9ju323v+Yw="
for whatever his session turns out to be. Not sure what the URI would look like.
Thank you @DL6ER
I was able to post with my password and then I recieved a sid in the json response
I was then able to use the sid to get a list of all endpoints
I think I'm good to continue now, thank you for the help.
I extended by description above and set up a pull request for the documentation of the upcoming Pi-hole v6.0 release:
Preview:
https://deploy-preview-950--pihole-docs.netlify.app/api/auth/
That's great info, thank you.
This topic was automatically closed 21 days after the last reply. New replies are no longer allowed.