Documentation: clarify api key usage for pfsense v1 vs v2

nopoz commented 2 months ago

Fixing pfSense widget documentation for usage with an API key. Current documentation has incorrect header of Authorization and a value of client_id client_token. The correct header name is X-API-Key and the value is the API key produced by the pfSense v2 API package. I have tested this format and it works as expected.

Example working config for reference:

    - pfSense:
        icon: pfsense.png
        href: https://pfsense.example.com
        description: router
        widget:
            type: pfsense
            url: https://pfsense.example.com
            headers:
              X-API-Key: 12345678
            wan: ix0
            version: 2
            fields: ["load", "memory", "wanStatus", "wanIP"]

pfSense API authorization documentation is here: https://pfrest.org/AUTHENTICATION_AND_AUTHORIZATION/

Proposed change

Closes Discussion #3716

Type of change

[ ] New service widget
[ ] Bug fix (non-breaking change which fixes an issue)
[ ] New feature (non-breaking change which adds functionality)
[X] Documentation only
[ ] Other (please explain)

Checklist:

[X] If applicable, I have added corresponding documentation changes.
[X] If applicable, I have reviewed the feature and / or service widget guidelines.
[X] I have checked that all code style checks pass using pre-commit hooks and linting checks.
[X] If applicable, I have tested my code for new features & regressions on both mobile & desktop devices, using the latest version of major browsers.

shamoon commented 2 months ago

I don’t have a pfsense but it seems odd to me that the current highly-specific documentation would be made-up, so the only way would be if something changed. Perhaps in the recent pfsense v2? If so, this change would be confusing

nopoz commented 2 months ago

I don’t have a pfsense but it seems odd to me that the current highly-specific documentation would be made-up, so the only way would be if something changed. Perhaps in the recent pfsense v2? If so, this change would be confusing

Looks like "Authorization: client_id client_token" is only for the v1 API version documented here: https://github.com/jaredhendrickson13/pfsense-api/tree/legacy?tab=readme-ov-file#authentication--authorization

The version I've added is for v2 only.

nopoz commented 2 months ago

I suppose there could be two different code blocks in the readme for v1 and another for v2?

shamoon commented 2 months ago

I suppose there could be two different code blocks in the readme for v1 and another for v2?

Yes, my point is it should be made clearer

github-actions[bot] commented 1 month ago

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new discussion for related concerns. See our contributing guidelines for more details.

gethomepage / homepage