> 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 parties that are hosted on this participant node. Unlike the Parties tab, local parties can be fetched in bulk.

Local parties are **not** loaded automatically on page load. To retrieve them, click **Fetch Local Parties**. While fetching is in progress, the existing list continues to be displayed and the fetch button is disabled. Once complete, the list updates to show all local parties.

{% hint style="info" %}
Only parties created through CatalyX are guaranteed to appear in the local parties list. Parties created directly via the Ledger API or gRPC may not be included.
{% 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**

Paste the full party ID of the party created in Part 1 directly into the **Primary Party** field. Do not use a party name — the field requires the full party address.

{% 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, 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 after fetch  | No parties created through CatalyX yet, or startup fetch is disabled | Click Fetch Local Parties manually; check `CANTON_CONSOLE_PARTIES_FETCH_ALL` setting |

## 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.