Claims in JWT for multi-party submission using JSON API

All the questions are related to using the JSON API. Assume a JWT has the following payload:

{
  "https://daml.com/ledger-api": {
    "ledgerId": "MyLedger",
    "applicationId": "foobar",
    "readAs": ["Alice"],
    "actAs": ["Bob"],
    "admin": true
  }
}

• Would this be a valid token, i.e. can Bob see Alice’s contracts but act as himself?
• Is "admin": true a valid property in the token?
• If admin is a valid property is it needed to use the party and package endpoints?
• If one can actAs “Bob” does it also mean one can readAs “Bob”?

Tamas_Kalcza:

Would this be a valid token, i.e. can Bob see Alice’s contracts but act as himself?

Absolutely, read queries will show you contacts visible to Bob or Alice (because actAs implieds readAs). Command submissions will be equivalent to submitMulti [Bob] [Alice] in Daml Script.

Tamas_Kalcza:

Is "admin": true a valid property in the token?

Yep, definitely valid. Doesn’t play a role for command submissions and queries but see next point.

Tamas_Kalcza:

If admin is a valid property is it needed to use the party and package endpoints?

First, let me clarify that the JSON API does not validate tokens. If you run your ledger without authorization enabled, the JSON API only uses the token to infer some information (e.g., the submitting party). The admin field is completely ignored in that case. The more interesting case is if your ledger is running with authorization. In that case the required claims for party and package endpoints are as follows:

1. All party endpoints require admin claims. This corresponds to the party management service on the Ledger API.
2. DAR upload also requires admin claims. This corresponds to the package management service on the Ledger API.
3. Listing packages and downloading individual packages does not require admin claims. This corresponds to the package service on the Ledger API (yes the names are slightly confusing here).

Do I read this right, that if authorisation is enabled for the ledger, then the admin claim is required if a party wishes to do party allocation or package upload?

Exactly

I think this is fairly obvious, so just for completeness: it is currently not possible to allow party management, but restrict package management, right? That is, for instance if a party could allocate parties, it could also upload packages.

Yes, there is nothing more fine-grained than admin claims and those allow for both package and party management. Perhaps worth pointing out that this is just inherited from the underlying ledger rather than being specific to the JSON API.

Yep, that was clear. Thank you.

I think this could actually be a potentially useful extension: to allow separate claims for party and package management. Not that I have a particular use case in mind, but I think assuming that those functions are always combined is an unnecessary restriction. In fact, following a proper separation of concerns, in a production setting I would actually recommend separating the two functions.