> ## 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/allocate

> The external party must be hosted (at least) on this node with either confirmation or observation permissions It can optionally be hosted on other nodes (then called a multi-hosted party). If hosted on additional nodes, explicit authorization of the hosting relationship must be performed on those nodes before the party can be used. Decentralized namespaces are supported but must be provided fully authorized by their owners.

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

<div class="x2mdx-ref-hero">
  <p class="x2mdx-ref-summary">The external party must be hosted (at least) on this node with either confirmation or observation permissions It can optionally be hosted on other nodes (then called a multi-hosted party). If hosted on additional nodes, explicit authorization of the hosting relationship must be performed on those nodes before the party can be used. Decentralized namespaces are supported but must be provided fully authorized by their owners.</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>
  </div>
</div>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url 'http://localhost:7575/v2/parties/external/allocate' \
    --header 'Authorization: Bearer $TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
    "synchronizer": "<string>",
    "onboardingTransactions": [
      {
        "transaction": "<string>",
        "signatures": [
          {
            "format": "<string>",
            "signature": "<string>",
            "signedBy": "<string>",
            "signingAlgorithmSpec": "<string>"
          }
        ]
      }
    ],
    "multiHashSignatures": [
      {
        "format": "<string>",
        "signature": "<string>",
        "signedBy": "<string>",
        "signingAlgorithmSpec": "<string>"
      }
    ],
    "identityProviderId": "<string>",
    "waitForAllocation": false,
    "userId": "<string>"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import json
  import requests

  url = "http://localhost:7575/v2/parties/external/allocate"
  headers = {'Authorization': 'Bearer <token>', 'Content-Type': 'application/json'}
  payload = json.loads(r'''{
    "synchronizer": "<string>",
    "onboardingTransactions": [
      {
        "transaction": "<string>",
        "signatures": [
          {
            "format": "<string>",
            "signature": "<string>",
            "signedBy": "<string>",
            "signingAlgorithmSpec": "<string>"
          }
        ]
      }
    ],
    "multiHashSignatures": [
      {
        "format": "<string>",
        "signature": "<string>",
        "signedBy": "<string>",
        "signingAlgorithmSpec": "<string>"
      }
    ],
    "identityProviderId": "<string>",
    "waitForAllocation": false,
    "userId": "<string>"
  }''')
  response = requests.request(
      "POST", url, headers=headers, json=payload
  )

  print(response.text)
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('http://localhost:7575/v2/parties/external/allocate', {
    method: 'POST',
    headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
    body: JSON.stringify({
    "synchronizer": "<string>",
    "onboardingTransactions": [
      {
        "transaction": "<string>",
        "signatures": [
          {
            "format": "<string>",
            "signature": "<string>",
            "signedBy": "<string>",
            "signingAlgorithmSpec": "<string>"
          }
        ]
      }
    ],
    "multiHashSignatures": [
      {
        "format": "<string>",
        "signature": "<string>",
        "signedBy": "<string>",
        "signingAlgorithmSpec": "<string>"
      }
    ],
    "identityProviderId": "<string>",
    "waitForAllocation": false,
    "userId": "<string>"
  }),
  });

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

  ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
      CURLOPT_URL => 'http://localhost:7575/v2/parties/external/allocate',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => 'POST',
      CURLOPT_POSTFIELDS => <<<'JSON'
  {
    "synchronizer": "<string>",
    "onboardingTransactions": [
      {
        "transaction": "<string>",
        "signatures": [
          {
            "format": "<string>",
            "signature": "<string>",
            "signedBy": "<string>",
            "signingAlgorithmSpec": "<string>"
          }
        ]
      }
    ],
    "multiHashSignatures": [
      {
        "format": "<string>",
        "signature": "<string>",
        "signedBy": "<string>",
        "signingAlgorithmSpec": "<string>"
      }
    ],
    "identityProviderId": "<string>",
    "waitForAllocation": false,
    "userId": "<string>"
  }
  JSON,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer <token>",
          "Content-Type: application/json"
      ],
  ]);

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

  ```go Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
  package main

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

  func main() {
    req, _ := http.NewRequest("POST", "http://localhost:7575/v2/parties/external/allocate", bytes.NewBufferString(`{
    "synchronizer": "<string>",
    "onboardingTransactions": [
      {
        "transaction": "<string>",
        "signatures": [
          {
            "format": "<string>",
            "signature": "<string>",
            "signedBy": "<string>",
            "signingAlgorithmSpec": "<string>"
          }
        ]
      }
    ],
    "multiHashSignatures": [
      {
        "format": "<string>",
        "signature": "<string>",
        "signedBy": "<string>",
        "signingAlgorithmSpec": "<string>"
      }
    ],
    "identityProviderId": "<string>",
    "waitForAllocation": false,
    "userId": "<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={"theme":{"light":"github-light","dark":"github-dark"}}
  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/allocate"))
      .header("Authorization", "Bearer <token>")
      .header("Content-Type", "application/json")
      .method("POST", HttpRequest.BodyPublishers.ofString("""
  {
    "synchronizer": "<string>",
    "onboardingTransactions": [
      {
        "transaction": "<string>",
        "signatures": [
          {
            "format": "<string>",
            "signature": "<string>",
            "signedBy": "<string>",
            "signingAlgorithmSpec": "<string>"
          }
        ]
      }
    ],
    "multiHashSignatures": [
      {
        "format": "<string>",
        "signature": "<string>",
        "signedBy": "<string>",
        "signingAlgorithmSpec": "<string>"
      }
    ],
    "identityProviderId": "<string>",
    "waitForAllocation": false,
    "userId": "<string>"
  }
  """))
      .build();
  var response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={"theme":{"light":"github-light","dark":"github-dark"}}
  require 'net/http'
  require 'uri'

  uri = URI('http://localhost:7575/v2/parties/external/allocate')
  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Bearer <token>'
  request['Content-Type'] = 'application/json'
  request.body = <<~JSON
  {
    "synchronizer": "<string>",
    "onboardingTransactions": [
      {
        "transaction": "<string>",
        "signatures": [
          {
            "format": "<string>",
            "signature": "<string>",
            "signedBy": "<string>",
            "signingAlgorithmSpec": "<string>"
          }
        ]
      }
    ],
    "multiHashSignatures": [
      {
        "format": "<string>",
        "signature": "<string>",
        "signedBy": "<string>",
        "signingAlgorithmSpec": "<string>"
      }
    ],
    "identityProviderId": "<string>",
    "waitForAllocation": false,
    "userId": "<string>"
  }
  JSON
  response = Net::HTTP.start(uri.hostname, uri.port) do |http|
    http.request(request)
  end
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "partyId": "<string>"
  }
  ```

  ```text 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  <string>
  ```

  ```json default theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "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 on which to onboard the party Required
</ParamField>

<ParamField body="onboardingTransactions" type="object[]" required>
  OpenAPI type: <code>SignedTransaction\[]</code>.

  TopologyTransactions to onboard the external party Can contain: - A namespace for the party. This can be either a single NamespaceDelegation, or DecentralizedNamespaceDefinition along with its authorized namespace owners in the form of NamespaceDelegations. May be provided, if so it must be fully authorized by the signatures in this request combined with the existing topology state. - A PartyToParticipant to register the hosting relationship of the party, and the party's signing keys and threshold. Must be provided. Required: must be non-empty

  <Expandable title="child attributes">
    <ParamField body="transaction" type="string" required>
      The serialized TopologyTransaction Required: must be non-empty
    </ParamField>

    <ParamField body="signatures" type="object[]">
      OpenAPI type: <code>Signature\[]</code>.

      Additional signatures for this transaction specifically Use for transactions that require additional signatures beyond the namespace key signatures e.g: PartyToParticipant must be signed by all registered keys Optional: can be empty

      <Expandable title="child attributes">
        <ParamField body="format" type="string" required>
          Required
        </ParamField>

        <ParamField body="signature" type="string" required>
          Required: must be non-empty
        </ParamField>

        <ParamField body="signedBy" type="string" required>
          The fingerprint/id of the keypair used to create this signature and needed to verify. Required
        </ParamField>

        <ParamField body="signingAlgorithmSpec" type="string" required>
          The signing algorithm specification used to produce this signature Required
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="multiHashSignatures" type="object[]">
  OpenAPI type: <code>Signature\[]</code>.

  Optional signatures of the combined hash of all onboarding\_transactions This may be used instead of providing signatures on each individual transaction Optional: can be empty

  <Expandable title="child attributes">
    <ParamField body="format" type="string" required>
      Required
    </ParamField>

    <ParamField body="signature" type="string" required>
      Required: must be non-empty
    </ParamField>

    <ParamField body="signedBy" type="string" required>
      The fingerprint/id of the keypair used to create this signature and needed to verify. Required
    </ParamField>

    <ParamField body="signingAlgorithmSpec" type="string" required>
      The signing algorithm specification used to produce this signature Required
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="identityProviderId" type="string">
  The id of the `Identity Provider` If not set, assume the party is managed by the default identity provider. Optional
</ParamField>

<ParamField body="waitForAllocation" type="boolean">
  When true, this RPC will attempt to wait for the party to be allocated on the synchronizer before returning. When false, the allocation will happen asynchronously. This is a best effort only as this synchronization is only possible for non decentralized parties (single hosting node). For decentralized parties, this flag is ignored. Defaults to true. Optional
</ParamField>

<ParamField body="userId" type="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
</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 allocated party id Required
</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/allocate operation changed in this snapshot.</p>
  </div>
</div>