Authentication

CBTC developer Quick Start

Authentication surfaces

CBTC integrations can authenticate to more than one service:

• Canton Ledger API: submit commands and query contract state for an authorized party.
• Canton Admin API: perform privileged participant operations such as package management. Most CBTC clients should not need this surface.
• BitSafe APIs: obtain account rules and participate in approved mint or redemption workflows.
• Source and artifact systems: access approved repositories or private release artifacts where required.

Use separate identities

Use distinct clients and credentials for development, test, and production. Separate administrative credentials from application credentials. Grant only the party rights and API scopes required for the workflow.

Configuration categories

A client can require an identity-provider URL, realm or audience, client identifier, client secret or approved key, grant type, token endpoint, Canton user, and target party. Exact variable names belong in the versioned configuration reference.

Safe setup

1. Create or obtain the approved service identity.
2. Assign the minimum Canton actAs and readAs rights.
3. Configure the approved audience and scopes.
4. Store secrets in a secret manager or protected local store.
5. Request a token through the approved flow.
6. Validate issuer, audience, expiry, and party authorization.
7. Run a read-only balance query before submitting a command.

Operational rules

• Never place tokens or secrets in documentation, screenshots, logs, shell history, or source control.
• Rotate credentials under an approved process.
• Treat authentication success and party authorization as separate checks.
• Do not retry a state-changing command only because token refresh or transport failed.
• Sanitize support evidence before sharing it.

Common failures

Failure	Check
Token request rejected	Provider URL, client, secret, grant, realm, and network access
Token accepted but query denied	Audience, scopes, Canton user rights, and party
Works in one environment only	Environment-specific client, endpoints, trust store, and party mapping
Intermittent failures	Clock skew, token expiry, refresh behavior, and connection reuse

Related pages

• CBTC environments and prerequisites
• CBTC developer Quick Start
• Install and validate CBTC DARs
• CBTC SDK, API, and integration reference
• CBTC security

Next step

👉 Test the connection: CBTC developer Quick Start.