Skip to content

docs: clarify auth vs adminAuth for wallet gateway configuration #804

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Ash-code183 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify auth vs adminAuth for wallet gateway configuration #804

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 11 additions & 5 deletions docs-main/integrations/wallet-gateway/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -372,18 +372,24 @@ Networks is an array, so you can define multiple networks in a single configurat
- _identityProviderId_ (required): Must match the `id` of an IDP defined in the `idps` section
- _ledgerApi_ (required): Configuration object for the Ledger API:
- _baseUrl_ (required): The base URL of the Canton validator's Ledger API (e.g., `"http://localhost:2975"` or `"https://ledger.example.com"`)
- _auth_ (required): Authentication configuration for normal ledger operations
- _adminAuth_ (optional): Authentication configuration for admin operations. Only needed for operations requiring elevated privileges
- _auth_ (required): Authentication configuration for normal ledger operations. This controls the login method presented to users in the UI, and should use **authorization_code** for interactive (user-facing) flows.
- _adminAuth_ (optional): Authentication configuration for admin operations. Only needed for operations requiring elevated privileges. This is used for backend machine-to-machine communication and should use **client_credentials** when the identity provider supports it.

**Authentication Methods:**

The Wallet Gateway supports three authentication methods for network access: **authorization_code**, **client_credentials**, and **self_signed**.

> [!IMPORTANT]
> **`auth` vs `adminAuth`**: The `auth` field determines the login method the user sees in the Wallet Gateway UI. The `adminAuth` field is used only for backend operations and is never presented to end users. This means:
> - For `auth` (user-facing): use **authorization_code** (interactive browser login) or **self_signed** (development)
> - For `adminAuth` (backend-only): use **client_credentials** (machine-to-machine) or **self_signed** (development)

**Recommendations:**

- **Production**: Use **client_credentials** for machine-to-machine authentication
- **Interactive/User-facing**: Use **authorization_code** for user-initiated flows
- **Development/Testing**: Use **self_signed** for local development
| Context | `auth` (user-facing) | `adminAuth` (backend) |
|---|---|---|
| **Production** | `authorization_code` | `client_credentials` |
| **Development/Testing** | `self_signed` | `self_signed` |

**Authorization Code:**

Expand Down