pfSense API package authentication mode token lifetime and revocation differ by version

Answer

Use the local credentials authentication mode with a dedicated, least‑privilege pfSense user.

Confirmed facts

• The local credentials mode delegates authentication to pfSense’s built‑in user manager; there is no package‑issued token to expire or refresh.
• Revocation is performed by disabling, deleting the user, or changing its password – behavior that does not change between package releases.
• Token lifetime concepts do not apply; the web server creates a session cookie or uses HTTP basic auth each request, which is validated against the user store on every call.

Likely explanation

API‑token mode stores a bearer token whose field names, header format, expiry handling and server‑side revocation tables have changed across package releases, making lifetime and revocation unpredictable. JWT mode is stateless; revocation before expiry relies on a version‑specific blacklist that may not exist, so its semantics are also unstable.

Steps to implement and maintain

1. Create a dedicated pfSense user with only the privileges required for the API calls (e.g., page-all or specific ACLs).
2. Configure the API package to use Local credentials auth mode and note the exact header (usually Authorization: Basic <base64(user:pass)> or session cookie).
3. Pin the API package version in your deployment pipeline to avoid unexpected changes.
4. After any package upgrade, re‑read the package’s auth configuration, verify the header format still matches the captured example, and repeat a test request.
5. If the test returns 401/403, re‑enroll the credential (reset password or recreate the user) and retry once.

Missing diagnostic detail

Does your security policy allow storing or transmitting a local pfSense user password (or its base64‑encoded form) in automation? If the answer is no, the recommendation shifts to API‑token mode – you would then need to pin the package version, capture the exact token header and expiry, and verify revocation on the target build.