Cannot just get a user by username

[svenfulen]

[/api/v2/user]

• pfSense Version: 2.8.1
• Package Version 2.8.1

In this version 2 of the API, you can't get details about a user via their username. It makes no sense to me that we have to list and filter users just to get the ID of a user who already has a unique username to do further actions on. Am I missing something here?

[jaredhendrickson13]

It's not just a matter of using a unique key unfortunately, it's a matter of using an indexed key. pfSense does not store users indexed by username in the config. Instead, users are stored by their position in the underlying array. That means using a username would not be a direct lookup key internally. Even if the API did accept a username in place of an ID, it would still need to scan through the full user list to find the matching entry. In other words, it would not be a true direct object lookup and the cost of lookup increases as the config grows.

If your goal is to find a user by username, the intended v2 operation is:

GET /api/v2/users?name=<username>

That endpoint is designed for collection filtering and will return only users that match the provided username. There are several filter operators you can choose to find exactly the object you need: https://pfrest.org/QUERIES_FILTERS_AND_SORTING/

For some additional context, this was a deliberate design decision in v2. Single-resource endpoints are meant to use direct index-based lookups, while collection endpoints handle filtered searches across a set of objects. This avoids using O(n) lookups in places that are expected to behave like direct resource fetches, which helps keep behavior predictable and reduces performance impact as configurations grow larger. This separation also became crucial in v2 because the object relationship handling relies on consistent, fast lookups wherever possible.