Skip to content
CCPEDIAby Unity Nodes
Documentation/Canton Network Docs/Ledger APIOpenAPIView on Canton Network Docs

POST /v2/users

POST
/
v2
/
users
Try it
cURL
Python
JavaScript
PHP
Go
Java
Ruby
curl --request POST \
  --url 'http://localhost:7575/v2/users' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}'
import json
import requests

url = "http://localhost:7575/v2/users"
headers = {'Authorization': 'Bearer <token>', 'Content-Type': 'application/json'}
payload = json.loads(r'''{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}''')
response = requests.request(
    "POST", url, headers=headers, json=payload
)

print(response.text)
const response = await fetch('http://localhost:7575/v2/users', {
  method: 'POST',
  headers: {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
},
  body: JSON.stringify({
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}),
});

console.log(await response.text());
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'http://localhost:7575/v2/users',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}
JSON,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer <token>",
        "Content-Type: application/json"
    ],
]);

$response = curl_exec($curl);
echo $response;
package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "http://localhost:7575/v2/users", bytes.NewBufferString(`{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}`))
  req.Header.Set("Authorization", "Bearer <token>")
  req.Header.Set("Content-Type", "application/json")
  response, _ := http.DefaultClient.Do(req)
  defer response.Body.Close()
  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:7575/v2/users"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}
"""))
    .build();
var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'uri'

uri = URI('http://localhost:7575/v2/users')
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = <<~JSON
{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}
JSON
response = Net::HTTP.start(uri.hostname, uri.port) do |http|
  http.request(request)
end
puts response.body
200
400
default
{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  }
}
<string>
{
  "code": "<string>",
  "cause": "<string>",
  "correlationId": "<string>",
  "traceId": "<string>",
  "context": {},
  "resources": [
    [
      "<string>"
    ]
  ],
  "errorCategory": 123,
  "grpcCodeValue": 123,
  "retryInfo": "<string>",
  "definiteAnswer": false
}

Create a new user.

cURL
Python
JavaScript
PHP
Go
Java
Ruby
curl --request POST \
  --url 'http://localhost:7575/v2/users' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}'
import json
import requests

url = "http://localhost:7575/v2/users"
headers = {'Authorization': 'Bearer <token>', 'Content-Type': 'application/json'}
payload = json.loads(r'''{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}''')
response = requests.request(
    "POST", url, headers=headers, json=payload
)

print(response.text)
const response = await fetch('http://localhost:7575/v2/users', {
  method: 'POST',
  headers: {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
},
  body: JSON.stringify({
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}),
});

console.log(await response.text());
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'http://localhost:7575/v2/users',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}
JSON,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer <token>",
        "Content-Type: application/json"
    ],
]);

$response = curl_exec($curl);
echo $response;
package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "http://localhost:7575/v2/users", bytes.NewBufferString(`{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}`))
  req.Header.Set("Authorization", "Bearer <token>")
  req.Header.Set("Content-Type", "application/json")
  response, _ := http.DefaultClient.Do(req)
  defer response.Body.Close()
  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:7575/v2/users"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}
"""))
    .build();
var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'uri'

uri = URI('http://localhost:7575/v2/users')
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = <<~JSON
{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  },
  "rights": [
    {
      "kind": {
        "CanActAs": {
          "value": {
            "party": "<string>"
          }
        }
      }
    }
  ]
}
JSON
response = Net::HTTP.start(uri.hostname, uri.port) do |http|
  http.request(request)
end
puts response.body
200
400
default
{
  "user": {
    "id": "<string>",
    "primaryParty": "<string>",
    "isDeactivated": false,
    "metadata": {
      "resourceVersion": "<string>",
      "annotations": {}
    },
    "identityProviderId": "<string>",
    "primaryPartyAuthentication": false
  }
}
<string>
{
  "code": "<string>",
  "cause": "<string>",
  "correlationId": "<string>",
  "traceId": "<string>",
  "context": {},
  "resources": [
    [
      "<string>"
    ]
  ],
  "errorCategory": 123,
  "grpcCodeValue": 123,
  "retryInfo": "<string>",
  "definiteAnswer": false
}

Authorizations

httpAuth

Authorization
string
required
HTTP bearer authentication. Send the token as Authorization: Bearer &lt;token&gt;. Ledger API standard JWT token

apiKeyAuth

Sec-WebSocket-Protocol
string
required
API key authentication in the header. Ledger API standard JWT token (websocket)

Body

application/json
user
object
required
OpenAPI type: User.Users and rights ///////////////// Users are used to dynamically manage the rights given to Daml applications. They are stored and managed per participant node.

Show child attributes

id
string
required
The user identifier, which must be a non-empty string of at most 128 characters that are either alphanumeric ASCII characters or one of the symbols ”@^$.!`-#+’~_|:()”. Required
primaryParty
string
The primary party as which this user reads and acts by default on the ledger provided it has the corresponding CanReadAs(primary_party) or CanActAs(primary_party) rights. Ledger API clients SHOULD set this field to a non-empty value for all users to enable the users to act on the ledger using their own Daml party. Users for participant administrators MAY have an associated primary party. Modifiable Optional
isDeactivated
boolean
When set, then the user is denied all access to the Ledger API. Otherwise, the user has access to the Ledger API as per the user’s rights. Modifiable Optional
metadata
object
OpenAPI type: 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

Show child attributes

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
object
OpenAPI type: Map_String.A set of modifiable key-value pairs that can be used to represent arbitrary, client-specific metadata. Constraints: 1. The total size over all keys and values cannot exceed 256kb in UTF-8 encoding. 2. Keys are composed of an optional prefix segment and a required name segment such that: - key prefix, when present, must be a valid DNS subdomain with at most 253 characters, followed by a ’/’ (forward slash) character, - name segment must have at most 63 characters that are either alphanumeric ([a-z0-9A-Z]), or a ’.’ (dot), ’-’ (dash) or ’_’ (underscore); and it must start and end with an alphanumeric character. 3. Values can be any non-empty strings. Keys with empty prefix are reserved for end-users. Properties set by external tools or internally by the participant server must use non-empty key prefixes. Duplicate keys are disallowed by the semantics of the protobuf3 maps. See: https://developers.google.com/protocol-buffers/docs/proto3#maps Annotations may be a part of a modifiable resource. Use the resource’s update RPC to update its annotations. In order to add a new annotation or update an existing one using an update RPC, provide the desired annotation in the update request. In order to remove an annotation using an update RPC, provide the target annotation’s key but set its value to the empty string in the update request. Modifiable Optional: can be empty
identityProviderId
string
The ID of the identity provider configured by Identity Provider Config If not set, assume the user is managed by the default identity provider. Optional
primaryPartyAuthentication
boolean
If set to true, the user may authenticate against the Ledger API by signing a Party JWT using the primary party’s signing key. Modifiable Optional
rights
object[]
OpenAPI type: Right[].The rights to be assigned to the user upon creation, which SHOULD include appropriate rights for the user.primary_party. Optional: can be empty

Show child attributes

kind
object
OpenAPI type: Kind.Required

Show child attributes

Variant 1
object

Show child attributes

CanActAs
object
required
OpenAPI type: CanActAs.

Show child attributes

value
object
required
OpenAPI type: CanActAs1.

Show child attributes

party
string
required
The right to authorize commands for this party. Required
Variant 2
object

Show child attributes

CanExecuteAs
object
required
OpenAPI type: CanExecuteAs.

Show child attributes

value
object
required
OpenAPI type: CanExecuteAs1.

Show child attributes

party
string
required
The right to prepare and execute submissions as this party. This right does not entitle the user to perform any reads. If reading is required, a separate ReadAs right must be added. Right to execute as a party is also implicitly contained in the CanActAs right. Required
Variant 3
object

Show child attributes

CanExecuteAsAnyParty
object
required
OpenAPI type: CanExecuteAsAnyParty.The rights of a user to prepare and execute transactions as any party. Its utility is predominantly for users that perform interactive submissions on behalf of many parties.

Show child attributes

value
object
required
OpenAPI type: CanExecuteAsAnyParty1.The rights of a user to prepare and execute transactions as any party. Its utility is predominantly for users that perform interactive submissions on behalf of many parties.
Variant 4
object

Show child attributes

CanReadAs
object
required
OpenAPI type: CanReadAs.

Show child attributes

value
object
required
OpenAPI type: CanReadAs1.

Show child attributes

party
string
required
The right to read ledger data visible to this party. Required
Variant 5
object

Show child attributes

CanReadAsAnyParty
object
required
OpenAPI type: CanReadAsAnyParty.The rights of a participant’s super reader. Its utility is predominantly for feeding external tools, such as PQS, continually without the need to change subscriptions as new parties pop in and out of existence.

Show child attributes

value
object
required
OpenAPI type: CanReadAsAnyParty1.The rights of a participant’s super reader. Its utility is predominantly for feeding external tools, such as PQS, continually without the need to change subscriptions as new parties pop in and out of existence.
Variant 6
object

Show child attributes

Empty
object
required
OpenAPI type: Empty8.
Variant 7
object

Show child attributes

IdentityProviderAdmin
object
required
OpenAPI type: IdentityProviderAdmin.The right to administer the identity provider that the user is assigned to. It means, being able to manage users and parties that are also assigned to the same identity provider.

Show child attributes

value
object
required
OpenAPI type: IdentityProviderAdmin1.The right to administer the identity provider that the user is assigned to. It means, being able to manage users and parties that are also assigned to the same identity provider.
Variant 8
object

Show child attributes

ParticipantAdmin
object
required
OpenAPI type: ParticipantAdmin.The right to administer the participant node.

Show child attributes

value
object
required
OpenAPI type: ParticipantAdmin1.The right to administer the participant node.

Responses

200

application/json
user
User
required
Users and rights ///////////////// Users are used to dynamically manage the rights given to Daml applications. They are stored and managed per participant node.

Show child attributes

id
string
required
The user identifier, which must be a non-empty string of at most 128 characters that are either alphanumeric ASCII characters or one of the symbols ”@^$.!`-#+’~_|:()”. Required
primaryParty
string
The primary party as which this user reads and acts by default on the ledger provided it has the corresponding CanReadAs(primary_party) or CanActAs(primary_party) rights. Ledger API clients SHOULD set this field to a non-empty value for all users to enable the users to act on the ledger using their own Daml party. Users for participant administrators MAY have an associated primary party. Modifiable Optional
isDeactivated
boolean
When set, then the user is denied all access to the Ledger API. Otherwise, the user has access to the Ledger API as per the user’s rights. Modifiable Optional
metadata
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

Show child attributes

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
Map_String
A set of modifiable key-value pairs that can be used to represent arbitrary, client-specific metadata. Constraints: 1. The total size over all keys and values cannot exceed 256kb in UTF-8 encoding. 2. Keys are composed of an optional prefix segment and a required name segment such that: - key prefix, when present, must be a valid DNS subdomain with at most 253 characters, followed by a ’/’ (forward slash) character, - name segment must have at most 63 characters that are either alphanumeric ([a-z0-9A-Z]), or a ’.’ (dot), ’-’ (dash) or ’_’ (underscore); and it must start and end with an alphanumeric character. 3. Values can be any non-empty strings. Keys with empty prefix are reserved for end-users. Properties set by external tools or internally by the participant server must use non-empty key prefixes. Duplicate keys are disallowed by the semantics of the protobuf3 maps. See: https://developers.google.com/protocol-buffers/docs/proto3#maps Annotations may be a part of a modifiable resource. Use the resource’s update RPC to update its annotations. In order to add a new annotation or update an existing one using an update RPC, provide the desired annotation in the update request. In order to remove an annotation using an update RPC, provide the target annotation’s key but set its value to the empty string in the update request. Modifiable Optional: can be empty
identityProviderId
string
The ID of the identity provider configured by Identity Provider Config If not set, assume the user is managed by the default identity provider. Optional
primaryPartyAuthentication
boolean
If set to true, the user may authenticate against the Ledger API by signing a Party JWT using the primary party’s signing key. Modifiable Optional

400

Invalid value, Invalid value for: body
text/plain
value
string
required

default

application/json
code
string
required
cause
string
required
correlationId
string
traceId
string
context
Map_String
required
resources
Tuple2_String_String[]
errorCategory
integer (int32)
required
grpcCodeValue
integer (int32)
retryInfo
string
definiteAnswer
boolean

History

Updated3.5

The POST /v2/users operation changed in this snapshot.