Overview
Every request to the LedgerSync API must be authenticated with a secret key passed as a Bearer token. This article explains how API keys work, the difference between sandbox and live keys, and how to keep them secure.
How to Authenticate
Include your secret key as a Bearer token in the Authorization header on every request:
Authorization: Bearer sk_test_your_key_here
Example using curl:
curl https://api-sandbox.ledgersyncappv2.com/v3/clients \
-H "Authorization: Bearer sk_test_..."
Two Environments, Two Key Prefixes
| Environment | Key Prefix | Base URL | Data |
|---|
| Sandbox | sk_test_... | https://api-sandbox.ledgersyncappv2.com/v3 | Test banks, fake data — safe to experiment |
| Live | sk_live_... | https://api.ledgersyncappv2.com/v3 | Real banks, real production data |
Important: Never mix sandbox and live keys. They route to different base URLs and completely separate data environments. A sandbox key will not work against the live base URL, and vice versa.
How to Get Your API Keys
- Log in to the LedgerSync developer portal at portal.ledgersyncappv2.com
- Go to API Keys in the left navigation menu
- Click Create an API key and choose your environment (Sandbox or Live)
- Copy the key immediately — the plaintext secret is shown only once. LedgerSync only stores a hash and cannot recover it later
- Store it securely in a secrets manager or environment variable on your server
Note: Live API keys require your account to have Live environment access approved. See the related article on requesting Live access.
Managing Your Keys
- List keys: View all keys for your account from the portal API Keys page. Key prefixes and IDs are shown, but not the plaintext secret.
- Revoke a key: Immediately stops all requests using that key. In-flight requests already past authentication continue running, but no new requests will be accepted. If you accidentally revoke the wrong key, simply create a new one.
- Filter by environment: Use the portal to view Sandbox and Live keys separately.
Security Best Practices
- Never embed keys client-side. Secret keys belong on your server only — never in a mobile app, browser JavaScript, or any client-facing code.
- Use environment variables. Store keys as environment variables or in a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault). Never hardcode them in source code.
- Rotate immediately if leaked. If a key is exposed, revoke it in the portal and create a new one right away.
- Keep test and live strictly separate. Use sandbox keys for development and testing only.
End-User Tokens
A few API flows act on behalf of a specific end-user (for example, submitting an MFA response during bank connection setup). Those flows use a short-lived bearer token — not your sk_ key — that you mint with your API key and hand to client-side code. This keeps your secret key server-side at all times.
The Trace ID Header
Every API response includes an X-LS-Trace-Id header. If you contact LedgerSync support about a specific request, include this value so the team can locate your exact call immediately.
Need Help?
Related Articles
- How to Request Live (Production) API Access
- LedgerSync API Overview: What You Can Build
- LedgerSync API: Getting Started (Quickstart Guide)