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.

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.

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.

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.

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

1

Open Keycloak

Log in to the Keycloak Admin Console and select the appropriate Realm.

2

Create a User

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

Recommended naming convention: cpm-${client}

3

Configure Credentials

Open the Credentials tab, set a password, and save your changes.

---

Part 3 — Create a User in CatalyX

1

Open Participant Users

Navigate to Participants, open the target Participant, open the Users tab, and click Create User.

2

Configure the User

Provide a username.

The username must match the Keycloak username exactly. Example: cpm-client

3

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.

You can copy the full party ID from the Local Parties or Parties tab on the Participant details page.

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.

---

Part 4 — Grant User Rights and Roles

Available Rights

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.

CanReadAs

ParticipantAdmin

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.

Grant the minimum required permissions. Avoid assigning ParticipantAdmin unless necessary.

---

Part 5 — Access the Wallet UI

1

Open the Wallet UI

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

2

Log in

Log in using the Keycloak credentials created in Part 2.

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

Use an incognito browser window to avoid Keycloak session conflicts.

---

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