Expose Ledger API

How to expose and access the Ledger API for a participant or validator in CatalyX Blockchain Manager.

Overview

This guide explains how to:

• expose the Ledger API for a participant or validator

• configure authentication and authorization

• configure Keycloak integration

• access the JSON Ledger API and gRPC Ledger API

• validate access tokens

• troubleshoot common Ledger API access issues

The Ledger API allows external applications to submit commands, query contracts, consume ledger events, and integrate with Canton applications.

Enabling the Ledger API exposes the participant API externally but does not cause ledger downtime or interrupt validator operations.

What is the Ledger API?

The Ledger API exposes services that allow applications to interact with the Canton ledger. It supports command submission, transaction streaming, active contract queries, and event subscriptions.

There are two primary API types:

API Type	Purpose
gRPC Ledger API	Native high-performance Canton integration
JSON Ledger API	REST/WebSocket-based integration

Architecture

The Ledger API uses OpenID Connect (OIDC), JWT access tokens, Keycloak authentication, and Canton authorization checks. Authorization is performed for every request.

Required token claims:

• aud — audience

• sub — subject

• scope — must include daml_ledger_api

---

Part 1 — Enable Ledger API Exposure

1

Open Validator Details

Navigate to Validators, select the target validator, and open Edit configuration.

2

Enable Ledger API Exposure

Locate the Ledger API or API Exposure settings and enable:

• JSON Ledger API exposure

• External API access

Save the configuration. After deployment, the participant exposes Ledger API endpoints externally.

3

Access the Ledger API URL

After enabling the API, the Ledger API URL becomes visible in the validator details page. Typical URL formats:

https://participant-${validator-name}.${domain}

https://json-api-${validator-name}.${domain}

Credentials are authenticated using Keycloak.

---

Part 2 — Configure Keycloak Authentication

Keycloak acts as the Identity Provider (IdP), OAuth Provider, and token issuer. Applications authenticate against Keycloak and receive JWT access tokens used by Canton.

Create a Realm

1

Open Keycloak

Log in to the Keycloak Admin Console and click Add Realm.

2

Configure the Realm

Provide a Realm Name and Display Name, then click Create.

Use separate realms per environment, for example: sandbox, production.

Create an OpenID Client

1

Open Clients

Navigate to Clients → Create.

2

Configure the Client

Provide:

• Client ID — recommended: canton-participants

• Protocol — openid-connect

3

Configure Access Type

Set Access Type to confidential and enable:

• Standard Flow

• Direct Access Grants

• Service Accounts

Save the configuration.

4

Configure Redirect URLs

Add the participant JSON API URL:

https://json-api-${participant}.${domain}/*

Save changes.

Create the daml_ledger_api Scope

1

Open Client Scopes

Navigate to Client Scopes → Create.

2

Configure the Scope

Create a scope named daml_ledger_api, enable Include In Token Scope, and save.

3

Assign the Scope to the Client

Navigate to Client → Client Scopes and add daml_ledger_api to Assigned Default Client Scopes.

Configure the Audience Mapper

The Ledger API validates the token audience against the participant identifier. Navigate to Client Scopes → daml_ledger_api → Mappers and create a mapper:

Field	Value
Name	audience-participant-mapper
Mapper Type	Audience
Included Custom Audience	participant ID

Enable Add to ID token and Add to access token.

Example audience value:

sandbox::12205d66c5f04ee07...

---

Part 3 — Configure Roles and Users

Navigate to Client → Roles → Add Role and create the required roles. Recommended roles:

• Participant_Admin

• Party

• Broker

• Borrower

• Lender

To create a user, navigate to Users → Add User, provide a username, email, and password, then navigate to User → Role Mappings and assign the appropriate client role (e.g. Participant_Admin).

---

Part 4 — Configure Canton Authorization

Configure the participant to validate JWT tokens against Keycloak:

ledger-api {
    address = localhost
    port = 6865
    auth-services = [{
        type = jwt-rs-256-jwks
        url = "http://localhost:8080/auth/realms/company/protocol/openid-connect/certs"
    }]
}

---

Part 5 — Generate an Access Token

Request a token from Keycloak:

curl -X POST \
  https://${keycloak}/auth/realms/${realm}/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=canton-participants" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=daml_ledger_api" \
  -d "username=participant_admin" \
  -d "password=${PASSWORD}"

The response contains an access token, expiration, and token type.

Validate the JWT Token

The JWT token must contain:

{
  "aud": "participantId",
  "sub": "userId",
  "scope": "daml_ledger_api",
  "exp": 1300819380
}

• The aud audience must match the participant ID

• The scope must include daml_ledger_api

---

Part 6 — Access the Ledger API

JSON Ledger API

Used for REST integrations, WebSocket event streaming, frontend applications, and lightweight integrations. Include the JWT token in every request:

Authorization: Bearer <access_token>

Common endpoints:

Endpoint	Purpose
/v2/updates/flats	Flat event stream
/v2/updates/trees	Transaction tree stream
/docs/openapi	OpenAPI documentation
/docs/asyncapi	AsyncAPI documentation

gRPC Ledger API

Used for backend services, high-performance integrations, and native Canton clients. Main services: Command Submission Service, Command Completion Service, Command Service.

Ledger Events

The Ledger API emits the following event types:

• Created Events

• Exercised Events

• Archived Events

• Transaction Tree Events

Applications consume events asynchronously.

---

Troubleshooting

Common Issues

Issue	Cause	Resolution
Unauthorized client	Incorrect client configuration	Verify confidential client settings
Invalid audience	Wrong participant audience	Update audience mapper
Missing scope	daml_ledger_api not assigned	Add default client scope
401 Unauthorized	Invalid token	Regenerate token
Ledger API inaccessible	API not exposed	Enable Ledger API exposure
Create Party button greyed out	Parties not yet loaded	Wait for synchronization to complete

Validation Checklist

Check	Expected Result
Ledger API enabled	External endpoint available
Keycloak client created	OAuth authentication works
daml_ledger_api scope configured	Tokens include scope
Audience mapper configured	Token audience valid
User roles assigned	API access granted
JWT token valid	Requests authorized

---

Best Practices

• Use confidential clients in production

• Separate environments by realm

• Use short-lived access tokens

• Restrict Participant_Admin role usage

• Always validate token scopes

• Use HTTPS-only endpoints

• Configure CORS for JSON API access

---

Additional References

• JSON Ledger API

• Ledger API Services

• Ledger API Proto Docs

• JSON API Reference