> For the complete documentation index, see [llms.txt](https://docs.catalyx.solutions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-1.11/network-and-node-management/parties-and-users.md).

# Parties & Users

## Overview

This section explains how to:

* View and manage parties on a participant.
* Create a User in Keycloak.
* Create a User in CatalyX.
* Assign user permissions and roles.
* Link a User to a Party.
* Access the Wallet UI.

This process is commonly used when onboarding a new customer, validator user, or application participant.

## Prerequisites

Before starting, ensure you have:

* Access to CatalyX Blockchain Manager
* Access to the Keycloak Admin Console
* Permissions to manage Participants and Users
* A deployed validator or participant

***

## Part 1 — View and Manage Parties

### What is a Party?

A Party represents an entity capable of creating contracts, interacting with contracts, and participating on the ledger. Each Party is hosted on one or more Participant Nodes.

### The Parties Tab

The **Parties** tab on the Participant details page allows you to look up any party — local or remote — by ID prefix. Enter at least two characters of a party ID to search. This tab is suitable for looking up a specific known party.

{% hint style="info" %}
The Parties tab does not load all parties automatically. In production environments a participant may be aware of hundreds of thousands of parties (the Canton Network MainNet has \~500,000+), making a full listing impractical.
{% endhint %}

### The Local Parties Tab

The **Local Parties** tab shows the parties hosted on this participant node. CatalyX reads them directly from the participant each time you open or refresh the tab, so the list loads within seconds.

### The External Parties Tab

The **External Parties** tab shows external parties and parties that were migrated onto this participant. Finding these requires a scan of the network, which can take a few minutes on large networks such as MainNet. The tab loads separately, so it never holds up the Local Parties list.

* The tab shows when the list was last scanned.
* Your browser keeps the last result, so the list appears straight away when you come back, and CatalyX only fetches what has changed since.
* A full scan runs automatically when there is no saved result or the last scan is more than a day old. You can also start a full rescan manually.
* While a scan runs, the previous list stays visible.

{% hint style="info" %}
If the participant cannot be reached, CatalyX shows an error and keeps the last list it loaded on screen.
{% endhint %}

### Create a Party

To allocate a new party on this participant, open the **Parties** tab and click **Add Party**. Provide a party name and any optional display information, then click **Save**.

After creation, the party becomes available on the ledger. Example party identifier:

```
alice::participant1::domain
```

***

## Part 2 — Create a User in Keycloak

{% stepper %}
{% step %}
**Open Keycloak**

Log in to the **Keycloak Admin Console** and select the appropriate Realm.
{% endstep %}

{% step %}
**Create a User**

Navigate to **Users** and click **Add User**. Enter a username.

{% hint style="info" %}
Recommended naming convention: `cpm-${client}`
{% endhint %}
{% endstep %}

{% step %}
**Configure Credentials**

Open the **Credentials** tab, set a password, and save your changes.
{% endstep %}
{% endstepper %}

***

## Part 3 — Create a User in CatalyX

{% stepper %}
{% step %}
**Open Participant Users**

Navigate to **Participants**, open the target Participant, open the **Users** tab, and click **Create User**.
{% endstep %}

{% step %}
**Configure the User**

Provide a username.

{% hint style="warning" %}
The username must match the Keycloak username exactly. Example: `cpm-client`
{% endhint %}
{% endstep %}

{% step %}
**Assign the Primary Party**

Select the party created in Part 1 from the **Primary Party** dropdown. The dropdown lists the parties hosted on this participant. If a party you just created is missing, click **Refresh Local Parties**.

You can also paste a party ID manually. Use the full party ID, not the party name.

{% hint style="info" %}
You can copy the full party ID from the **Local Parties** or **Parties** tab on the Participant details page.
{% endhint %}

{% hint style="warning" %}
If the party ID entered does not exist on this participant, CatalyX will display an error. Verify the party ID is correct and that the party is hosted on this participant before proceeding.
{% endhint %}
{% endstep %}
{% endstepper %}

***

## Part 4 — Grant User Rights and Roles

### Available Rights

{% tabs %}
{% tab title="CanActAs" %}
Allows the user to act on behalf of the Party, submit transactions, and interact with contracts.

**Recommended for:** operational users, wallet users, application users.
{% endtab %}

{% tab title="CanReadAs" %}
Allows the user to view ledger data and read contracts. Does **not** allow submitting transactions or acting on behalf of the Party.

**Recommended for:** auditors, monitoring users, read-only access.
{% endtab %}

{% tab title="ParticipantAdmin" %}
Provides administrative access to the Participant. Use carefully.

**Recommended only for:** platform administrators, DevOps operators.
{% endtab %}
{% endtabs %}

### Recommended Rights by User Type

| User Type   | Recommended Rights |
| ----------- | ------------------ |
| Wallet user | CanActAs           |
| Auditor     | CanReadAs          |
| Admin       | ParticipantAdmin   |

### Assign Rights

Under **User Rights**, choose the appropriate role and select the target Party from the dropdown (use **Refresh** to reload the list), then click **Save**.

{% hint style="info" %}
Grant the minimum required permissions. Avoid assigning `ParticipantAdmin` unless necessary.
{% endhint %}

***

## Part 5 — Access the Wallet UI

{% stepper %}
{% step %}
**Open the Wallet UI**

Open the Wallet UI URL for your validator. Example: `https://wallet-${validator-name}.${domain}`
{% endstep %}

{% step %}
**Log in**

Log in using the Keycloak credentials created in Part 2.
{% endstep %}
{% endstepper %}

After login, verify that the wallet opens successfully, balances are visible, and Party permissions work correctly.

{% hint style="warning" %}
Use an incognito browser window to avoid Keycloak session conflicts.
{% endhint %}

***

## Validation Checklist

| Validation            | Expected Result                |
| --------------------- | ------------------------------ |
| Party created         | Party visible in CatalyX       |
| Keycloak user created | User can authenticate          |
| CatalyX user created  | User visible under Participant |
| Rights assigned       | User has correct access        |
| Wallet login works    | User can access wallet         |

## Troubleshooting

| Issue                                         | Cause                                                   | Resolution                                                                |
| --------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------- |
| User cannot log in                            | Incorrect Keycloak credentials                          | Reset password                                                            |
| Wallet access denied                          | Missing CanActAs role                                   | Grant correct rights                                                      |
| User not linked to Party                      | Primary Party not assigned                              | Update user configuration                                                 |
| Primary Party field shows an error            | Party ID does not exist on this participant             | Verify the full party ID from the Local Parties tab                       |
| User visible in Keycloak but not CatalyX      | CatalyX user not created                                | Create user in Participant Users tab                                      |
| Session conflicts during login                | Existing Keycloak session                               | Use incognito browser                                                     |
| Local Parties list is empty or shows an error | Participant is not running or not connected to a domain | Check that the participant is running and connected, then refresh the tab |

## Best Practices

* Use consistent naming conventions across Keycloak and CatalyX
* Match Keycloak and CatalyX usernames exactly
* Copy party IDs directly from the Local Parties tab to avoid typos
* Grant minimum required permissions
* Avoid assigning `ParticipantAdmin` unless necessary
* Use separate users for admin and operational activities


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-1.11/network-and-node-management/parties-and-users.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.