--- title: "POST /v2/parties" method: POST path: "/v2/parties" --- # POST /v2/parties `POST /v2/parties` Allocates a new party on a ledger and adds it to the set managed by the participant. Caller specifies a party identifier suggestion, the actual identifier allocated might be different and is implementation specific. Caller can specify party metadata that is stored locally on the participant. This call may: - Succeed, in which case the actual allocated identifier is visible in the response. - Respond with a gRPC error daml-on-kv-ledger: suggestion's uniqueness is checked by the validators in the consensus layer and call rejected if the identifier is already present. canton: completely different globally unique identifier is allocated. Behind the scenes calls to an internal protocol are made. As that protocol is richer than the surface protocol, the arguments take implicit values The party identifier suggestion must be a valid party name. Party names are required to be non-empty US-ASCII strings built from letters, digits, space, colon, minus and underscore limited to 255 chars ## Request body - AllocatePartyRequest — Required authorization: ``HasRight(ParticipantAdmin) OR IsAuthenticatedIdentityProviderAdmin(identity_provider_id) OR IsAuthenticatedUser(user_id)`` - `partyIdHint` string — A hint to the participant which party ID to allocate. It can be ignored. Must be a valid PartyIdString (as described in ``value.proto``). Optional - `localMetadata` ObjectMeta — Represents metadata corresponding to a participant resource (e.g. a participant user or participant local information about a party). Based on ``ObjectMeta`` meta used in Kubernetes API. See https://github.com/kubernetes/apimachinery/blob/master/pkg/apis/meta/v1/generated.proto#L640 - `resourceVersion` string — An opaque, non-empty value, populated by a participant server which represents the internal version of the resource this ``ObjectMeta`` message is attached to. The participant server will change it to a unique value each time the corresponding resource is updated. You must not rely on the format of resource version. The participant server might change it without notice. You can obtain the newest resource version value by issuing a read request. You may use it for concurrent change detection by passing it back unmodified in an update request. The participant server will then compare the passed value with the value maintained by the system to determine if any other updates took place since you had read the resource version. Upon a successful update you are guaranteed that no other update took place during your read-modify-write sequence. However, if another update took place during your read-modify-write sequence then your update will fail with an appropriate error. Concurrent change control is optional. It will be applied only if you include a resource version in an update request. When creating a new instance of a resource you must leave the resource version empty. Its value will be populated by the participant server upon successful resource creation. Optional - `annotations` MapString - `identityProviderId` string — The id of the ``Identity Provider`` If not set, assume the party is managed by the default identity provider or party is not hosted by the participant. Optional - `synchronizerId` string — The synchronizer, on which the party should be allocated. For backwards compatibility, this field may be omitted, if the participant is connected to only one synchronizer. Otherwise a synchronizer must be specified. Optional - `userId` string — The user who will get the act_as rights to the newly allocated party. If set to an empty string (the default), no user will get rights to the party. Optional ## Response `200` - AllocatePartyResponse - `partyDetails` PartyDetails, required - `party` string, required — The stable unique identifier of a Daml party. Must be a valid PartyIdString (as described in ``value.proto``). Required - `isLocal` boolean — true if party is hosted by the participant and the party shares the same identity provider as the user issuing the request. Optional - `localMetadata` ObjectMeta — Represents metadata corresponding to a participant resource (e.g. a participant user or participant local information about a party). Based on ``ObjectMeta`` meta used in Kubernetes API. See https://github.com/kubernetes/apimachinery/blob/master/pkg/apis/meta/v1/generated.proto#L640 - `resourceVersion` string — An opaque, non-empty value, populated by a participant server which represents the internal version of the resource this ``ObjectMeta`` message is attached to. The participant server will change it to a unique value each time the corresponding resource is updated. You must not rely on the format of resource version. The participant server might change it without notice. You can obtain the newest resource version value by issuing a read request. You may use it for concurrent change detection by passing it back unmodified in an update request. The participant server will then compare the passed value with the value maintained by the system to determine if any other updates took place since you had read the resource version. Upon a successful update you are guaranteed that no other update took place during your read-modify-write sequence. However, if another update took place during your read-modify-write sequence then your update will fail with an appropriate error. Concurrent change control is optional. It will be applied only if you include a resource version in an update request. When creating a new instance of a resource you must leave the resource version empty. Its value will be populated by the participant server upon successful resource creation. Optional - `annotations` MapString - `identityProviderId` string — The id of the ``Identity Provider`` Optional, if not set, there could be 3 options: 1. the party is managed by the default identity provider. 2. party is not hosted by the participant. 3. party is hosted by the participant, but is outside of the user's identity provider. Optional ## Other responses - `400` — Invalid value, Invalid value for: body - `default` --- [API](https://skmtc.dev/canton/apis/json-ledger-api-http-endpoints.md) · [All operations](https://skmtc.dev/canton/apis/json-ledger-api-http-endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/canton/json-ledger-api-http-endpoints/revisions/296292e8b8f1/schema)