Authentication

Authenticate Soledgic resource requests with API keys.

API Keys

Every request to the treasury API must include your key in the x-api-key header.

curl -X POST https://api.soledgic.com/v1/participants \
  -H "x-api-key: slk_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"participant_id": "creator_456"}'

Sandbox vs Live Keys

Sandbox and live are isolated. Participants, wallets, holds, and payouts created with a sandbox key never touch your live environment.

Sandbox

Keys start with slk_test_

• Sandbox ledger state
• Safe for integration and retry testing
• No live payout, wallet funding, or billing impact

Live

Keys start with slk_live_

• Production treasury state
• Real participant balances and payouts
• Use only from secure server-side environments

Scoped Keys

Scoped keys are fail-closed. If an endpoint requires a scope your key does not have, Soledgic returns 403before running the operation.

Scope	Use for
`read`	Reports, balances, transactions, exports
`payments`	Checkout, refunds, holds, reversals, transfers
`payouts`	Creator and platform payout execution
`creators`	Participants, creator access, creator tax profile actions
`credits`	Issuing, converting, and redeeming credits
`webhooks`	Webhook endpoint management
`accounting`	Expenses, invoices, bills, bank imports, reconciliations
`risk`	Fraud policies, risk evaluations, alert configuration

Keeping Keys Secure

API keys authorize money movement and treasury state changes. Treat them like production secrets.

✓

Keep keys server-side

Never expose live keys in browser code or mobile bundles

✓

Store keys in environment variables

Use your host secret manager or deployment environment settings

✓

Rotate keys on suspicion of exposure

Treat compromised keys as an incident, not a cleanup task

✗

Do not commit keys to git

Add env files to .gitignore and protect CI logs

Using Environment Variables

Keep the API key outside your source tree and inject it at runtime.

.env

SOLEDGIC_API_KEY=slk_test_abc123...

Node.js

const apiKey = process.env.SOLEDGIC_API_KEY;

fetch('https://api.soledgic.com/v1/checkout-sessions', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    participant_id: 'creator_456',
    amount: 2999,
    currency: 'USD',
    success_url: 'https://example.com/success',
  }),
});

Python

import os
import requests

api_key = os.environ.get('SOLEDGIC_API_KEY')

response = requests.get(
    'https://api.soledgic.com/v1/wallets?owner_id=creator_456&wallet_type=creator_earnings',
    headers={'x-api-key': api_key},
)

Authentication Errors

Authentication failures return a consistent envelope.

Status	Error	Cause
`401`	Missing API key	No x-api-key header was provided
`401`	Invalid API key	Key is unknown, revoked, or for a different environment
`403`	Ledger suspended	The owning account is suspended or inactive

Rate Limits

Different classes of endpoints have different pressure profiles.

Endpoint class	Typical limit
Read endpoints	1,000 requests/minute
Treasury writes: checkout, payout, refund, hold release	Lower burst ceilings with stricter replay protection
Internal or webhook-driven operations	Policy-specific

When rate limited, the API returns 429 Too Many Requestsand includes retry headers.

Next Steps

API Reference →SDKs & Libraries →