> ## Documentation Index
> Fetch the complete documentation index at: https://cantonfoundation-generated-reference-full-stack-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v2/parties/external/generate-topology

> You may use this endpoint to generate the common external topology transactions which can be signed externally and uploaded as part of the allocate party process Note that this request will create a normal namespace using the same key for the identity as for signing. More elaborate schemes such as multi-signature or decentralized parties require you to construct the topology transactions yourself.

<div class="x2mdx-ref-page x2mdx-ref-page--operation x2mdx-ref-page--manual-api" />

<div class="x2mdx-ref-hero">
  <p class="x2mdx-ref-summary">You may use this endpoint to generate the common external topology transactions which can be signed externally and uploaded as part of the allocate party process Note that this request will create a normal namespace using the same key for the identity as for signing. More elaborate schemes such as multi-signature or decentralized parties require you to construct the topology transactions yourself.</p>

  <div class="x2mdx-ref-badges">
    <span class="x2mdx-ref-badge x2mdx-ref-badge--protocol">OpenAPI</span>

    <a class="x2mdx-ref-badge x2mdx-ref-badge--changed" href="#history-updated-3-5">Updated 3.5</a>

    <a class="x2mdx-ref-badge x2mdx-ref-badge--added" href="#history-added-3-4">Added 3.4</a>
  </div>
</div>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'http://localhost:7575/v2/parties/external/generate-topology' \
    --header 'Authorization: Bearer $TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
    "synchronizer": "<string>",
    "partyHint": "<string>",
    "publicKey": {
      "format": "CRYPTO_KEY_FORMAT_DER_X509_SUBJECT_PUBLIC_KEY_INFO",
      "keyData": "<string>",
      "keySpec": "SIGNING_KEY_SPEC_EC_CURVE25519"
    },
    "localParticipantObservationOnly": false,
    "otherConfirmingParticipantUids": [
      "<string>"
    ],
    "confirmationThreshold": 123,
    "observingParticipantUids": [
      "<string>"
    ]
  }'
  ```

  ```python Python theme={null}
  import json
  import requests

  url = "http://localhost:7575/v2/parties/external/generate-topology"
  headers = {'Authorization': 'Bearer <token>', 'Content-Type': 'application/json'}
  payload = json.loads(r'''{
    "synchronizer": "<string>",
    "partyHint": "<string>",
    "publicKey": {
      "format": "CRYPTO_KEY_FORMAT_DER_X509_SUBJECT_PUBLIC_KEY_INFO",
      "keyData": "<string>",
      "keySpec": "SIGNING_KEY_SPEC_EC_CURVE25519"
    },
    "localParticipantObservationOnly": false,
    "otherConfirmingParticipantUids": [
      "<string>"
    ],
    "confirmationThreshold": 123,
    "observingParticipantUids": [
      "<string>"
    ]
  }''')
  response = requests.request(
      "POST", url, headers=headers, json=payload
  )

  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:7575/v2/parties/external/generate-topology', {
    method: 'POST',
    headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
    body: JSON.stringify({
    "synchronizer": "<string>",
    "partyHint": "<string>",
    "publicKey": {
      "format": "CRYPTO_KEY_FORMAT_DER_X509_SUBJECT_PUBLIC_KEY_INFO",
      "keyData": "<string>",
      "keySpec": "SIGNING_KEY_SPEC_EC_CURVE25519"
    },
    "localParticipantObservationOnly": false,
    "otherConfirmingParticipantUids": [
      "<string>"
    ],
    "confirmationThreshold": 123,
    "observingParticipantUids": [
      "<string>"
    ]
  }),
  });

  console.log(await response.text());
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
      CURLOPT_URL => 'http://localhost:7575/v2/parties/external/generate-topology',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => 'POST',
      CURLOPT_POSTFIELDS => <<<'JSON'
  {
    "synchronizer": "<string>",
    "partyHint": "<string>",
    "publicKey": {
      "format": "CRYPTO_KEY_FORMAT_DER_X509_SUBJECT_PUBLIC_KEY_INFO",
      "keyData": "<string>",
      "keySpec": "SIGNING_KEY_SPEC_EC_CURVE25519"
    },
    "localParticipantObservationOnly": false,
    "otherConfirmingParticipantUids": [
      "<string>"
    ],
    "confirmationThreshold": 123,
    "observingParticipantUids": [
      "<string>"
    ]
  }
  JSON,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer <token>",
          "Content-Type: application/json"
      ],
  ]);

  $response = curl_exec($curl);
  echo $response;
  ```

  ```go Go theme={null}
  package main

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

  func main() {
    req, _ := http.NewRequest("POST", "http://localhost:7575/v2/parties/external/generate-topology", bytes.NewBufferString(`{
    "synchronizer": "<string>",
    "partyHint": "<string>",
    "publicKey": {
      "format": "CRYPTO_KEY_FORMAT_DER_X509_SUBJECT_PUBLIC_KEY_INFO",
      "keyData": "<string>",
      "keySpec": "SIGNING_KEY_SPEC_EC_CURVE25519"
    },
    "localParticipantObservationOnly": false,
    "otherConfirmingParticipantUids": [
      "<string>"
    ],
    "confirmationThreshold": 123,
    "observingParticipantUids": [
      "<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))
  }
  ```

  ```java Java theme={null}
  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/parties/external/generate-topology"))
      .header("Authorization", "Bearer <token>")
      .header("Content-Type", "application/json")
      .method("POST", HttpRequest.BodyPublishers.ofString("""
  {
    "synchronizer": "<string>",
    "partyHint": "<string>",
    "publicKey": {
      "format": "CRYPTO_KEY_FORMAT_DER_X509_SUBJECT_PUBLIC_KEY_INFO",
      "keyData": "<string>",
      "keySpec": "SIGNING_KEY_SPEC_EC_CURVE25519"
    },
    "localParticipantObservationOnly": false,
    "otherConfirmingParticipantUids": [
      "<string>"
    ],
    "confirmationThreshold": 123,
    "observingParticipantUids": [
      "<string>"
    ]
  }
  """))
      .build();
  var response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'uri'

  uri = URI('http://localhost:7575/v2/parties/external/generate-topology')
  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Bearer <token>'
  request['Content-Type'] = 'application/json'
  request.body = <<~JSON
  {
    "synchronizer": "<string>",
    "partyHint": "<string>",
    "publicKey": {
      "format": "CRYPTO_KEY_FORMAT_DER_X509_SUBJECT_PUBLIC_KEY_INFO",
      "keyData": "<string>",
      "keySpec": "SIGNING_KEY_SPEC_EC_CURVE25519"
    },
    "localParticipantObservationOnly": false,
    "otherConfirmingParticipantUids": [
      "<string>"
    ],
    "confirmationThreshold": 123,
    "observingParticipantUids": [
      "<string>"
    ]
  }
  JSON
  response = Net::HTTP.start(uri.hostname, uri.port) do |http|
    http.request(request)
  end
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "partyId": "<string>",
    "publicKeyFingerprint": "<string>",
    "topologyTransactions": [
      "<string>"
    ],
    "multiHash": "<string>"
  }
  ```

  ```text 400 theme={null}
  <string>
  ```

  ```json default theme={null}
  {
    "code": "<string>",
    "cause": "<string>",
    "correlationId": "<string>",
    "traceId": "<string>",
    "context": {},
    "resources": [
      [
        "<string>"
      ]
    ],
    "errorCategory": 123,
    "grpcCodeValue": 123,
    "retryInfo": "<string>",
    "definiteAnswer": false
  }
  ```
</ResponseExample>

## Authorizations

### httpAuth

<ParamField header="Authorization" type="string" required>
  HTTP bearer authentication. Send the token as `Authorization: Bearer &lt;token&gt;`. Ledger API standard JWT token
</ParamField>

### apiKeyAuth

<ParamField header="Sec-WebSocket-Protocol" type="string" required>
  API key authentication in the header. Ledger API standard JWT token (websocket)
</ParamField>

## Body

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ParamField body="synchronizer" type="string" required>
  Synchronizer-id for which we are building this request. Required
</ParamField>

<ParamField body="partyHint" type="string" required>
  The actual party id will be constructed from this hint and a fingerprint of the public key Required
</ParamField>

<ParamField body="publicKey" type="object" required>
  OpenAPI type: <code>SigningPublicKey</code>.

  Public key Required

  <Expandable title="child attributes">
    <ParamField body="format" type="string" required>
      The serialization format of the public key Required
    </ParamField>

    <ParamField body="keyData" type="string" required>
      Serialized public key in the format specified above Required: must be non-empty
    </ParamField>

    <ParamField body="keySpec" type="string" required>
      The key specification Required
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="localParticipantObservationOnly" type="boolean">
  If true, then the local participant will only be observing, not confirming. Default false. Optional
</ParamField>

<ParamField body="otherConfirmingParticipantUids" type="string[]">
  Other participant ids which should be confirming for this party Optional: can be empty
</ParamField>

<ParamField body="confirmationThreshold" type="number">
  OpenAPI type: <code>integer (int32)</code>.

  Confirmation threshold >= 1 for the party. Defaults to all available confirmers (or if set to 0). Optional
</ParamField>

<ParamField body="observingParticipantUids" type="string[]">
  Other observing participant ids for this party Optional: can be empty
</ParamField>

## Responses

### 200

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="partyId" type="string" required>
  The generated party id Required
</ResponseField>

<ResponseField name="publicKeyFingerprint" type="string" required>
  The fingerprint of the supplied public key Required
</ResponseField>

<ResponseField name="topologyTransactions" type="string[]" required>
  The serialized topology transactions which need to be signed and submitted as part of the allocate party process Note that the serialization includes the versioning information. Therefore, the transaction here is serialized as an `UntypedVersionedMessage` which in turn contains the serialized `TopologyTransaction` in the version supported by the synchronizer. Required: must be non-empty
</ResponseField>

<ResponseField name="multiHash" type="string" required>
  the multi-hash which may be signed instead of each individual transaction Required: must be non-empty
</ResponseField>

### 400

Invalid value, Invalid value for: body

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">text/plain</span>
</div>

<ResponseField name="value" type="string" required />

### default

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="code" type="string" required />

<ResponseField name="cause" type="string" required />

<ResponseField name="correlationId" type="string" />

<ResponseField name="traceId" type="string" />

<ResponseField name="context" type="Map_String" required />

<ResponseField name="resources" type="Tuple2_String_String[]" />

<ResponseField name="errorCategory" type="integer (int32)" required />

<ResponseField name="grpcCodeValue" type="integer (int32)" />

<ResponseField name="retryInfo" type="string" />

<ResponseField name="definiteAnswer" type="boolean" />

## History

<div class="x2mdx-ref-history" aria-label="Reference history">
  <div class="x2mdx-ref-history-event x2mdx-ref-history-event--changed" id="history-updated-3-5">
    <div class="x2mdx-ref-history-event-head">
      <span class="x2mdx-ref-history-event-label">Updated</span>
      <code class="x2mdx-ref-history-event-version">3.5</code>
    </div>

    <p class="x2mdx-ref-history-event-detail">The POST /v2/parties/external/generate-topology operation was updated in this snapshot.</p>
  </div>

  <div class="x2mdx-ref-history-event x2mdx-ref-history-event--introduced" id="history-added-3-4">
    <div class="x2mdx-ref-history-event-head">
      <span class="x2mdx-ref-history-event-label">Added</span>
      <code class="x2mdx-ref-history-event-version">3.4</code>
    </div>
  </div>
</div>