API: User permissions object doesn't take groups into account

[Iizuki]

Summary

The user permissions object acquired e.g. from GET /users/me API endpoint doesn't directly tell what permissions the user has. Rights inherited from groups are not visible here.

Example

A trimmed example of the returned object:

{
  "superuser": 0,
  "admin": 0,
  "import": 0,
  "reports.view": 0,
  "assets.view": 1,
  "assets.create": 1,
  "assets.edit": 1,
  "assets.delete": 1,
  "assets.checkin": 1,
  "assets.checkout": 1,
  "assets.audit": 1,
  "assets.view.requestable": 1,
  "assets.view.encrypted_custom_fields": -1,
  "accessories.view": -1,
  ...
}

My expectation was that the values were booleans serialized as 1/0, but then I discovered that it can be -1 too. So in fact the legend is:

Value	Meaning
1	Grant
0	Inherit
-1	Deny

I.e. just encoding what you can see in the user settings. This is not documented.

The issue

This is unexpected, and not really useful either. Zeroes (which are really common in the wild) don't tell whether the user has the right or not.

Solutions

Some ideas how to improve the API.

Return resolved permissions

Resolve the inherited permissions serverside and just return booleans. I don't think API users really care which way the permission came through.

This would be my preference.

Use an enum instead

Return unresolved permissions just as now, but serialize them into an enum that makes it clear what's going on. For example: "grant", "inherit" and "deny".

[snipe]

That's sort of expected behavior though, since you're looking at the user object itself. I think we'd have to create a second permissions listing in order for this to make sense.

Re: enums: Changing the shape of the API in this way would be massively disruptive to a lot of existing workflows.

[Iizuki]

Yeah I suppose it can be nice to have this kinda verbatim listing in some situations, but the effective permissions would definitely be of interest too.

Perhaps at least document the C-style enum values?