Documentation on API permissions?

[chrullrich]

Hello,
is there some documentation on what exactly the "Check" lines in the API viewer (https://pve.proxmox.com/pve-docs/api-viewer/) mean? I can make sense of some of it, but I would like to be sure I understand it correctly.

Examples:

• GET /access/domains/{realm}: Check: ["perm","/access/realm",["Realm.Allocate","Sys.Audit"],"any",1]
  I think this means either ("any of") Realm.Allocate or Sys.Audit on that path, but what is the 1 at the end? Surely not "any one of them" as opposed to "any two"?
• POST /access/domains/{realm}/sync: Check: ["and",["perm","/access/realm/{realm}",["Realm.AllocateUser"]],["perm","/access/groups",["User.Modify"]]]
  One and the other.
• GET /access/tfa/{userid}: Check: ["or",["userid-param","self"],["userid-group",["User.Modify","Sys.Audit"]]]
  Allowed when you are retrieving data on yourself, or you have the two permissions on a group that contains the userid, perhaps?

The last one, and the fact that the API viewer sometimes describes required permissions as explanatory text, makes me wonder if these "Check" expressions are merely pseudocode and there is no definite specification for them.

Thanks for any pointers.

 

[fabian]

https://git.proxmox.com/?p=pve-acce...665fcdef50ba80e319a;hb=refs/heads/master#l450

so you pretty much guessed correctly

- 'and' and 'or' have the expected semantics
- 'any', '1' is actually 'any' => '1', as in, set the 'any' option to true, and yes, it refers to "any of these privileges"
- 'userid-param' means check the value of the userid parameter of the API call, with the value 'self' meaning it must match the authenticated user
- 'userid-group' is the most complicated one, it means you either have one of those privs on all groups and thus transitively all users, or you have it one of the groups of the user in the userid parameter (there's other special cases there as well that are not relevant for this particular API call)

note that not all checks are encodable in the schema, in which case there should be a human readable description giving you more information (e.g., sometimes checks might depend on existing guest config values, or only run if certain parameters are set).

 

[chrullrich]

The code is documentation enough, I see ...

Thank you very much, and I will go dig my way through that logic.