Getting started

Authentication

Server-to-server calls use a Tunnel secret key. Dashboard sessions use Cognito JWT — you do not need a JWT to charge customers from your backend.

How to get your API key

  1. Open the Tunnel dashboard and sign in.
  2. Make sure the top bar shows Test Mode while you are integrating (switch to Live Mode only for production keys).
  3. Go to API Keys in the sidebar.
  4. Click Create API key. Choose a name, environment (test or live), and at least one allowed domain (e.g. api.yourapp.com).
  5. Confirm with your account password to reveal the secret. Copy it once — Tunnel never lists plaintext keys again.

Key prefixes

  • sk_test_… — sandbox / test providers only
  • sk_live_… — live providers only

Request headers

Required headers
Authorization: Bearer sk_test_your_api_key
Content-Type: application/json
Idempotency-Key: order_12345
X-Tunnel-Origin: https://api.yourapp.com
HeaderWhen
AuthorizationAlways — Bearer secret key
Content-TypeJSON bodies
Idempotency-KeyRecommended on POST /transactions
X-Tunnel-OriginServer callers without browser Origin/Referer — must match an allowed domain on the key

Allowed domains

Each key is locked to hostnames you register. Tunnel checks Origin, Referer, or X-Tunnel-Origin. Mismatches return 401.

Minimal authenticated call

GET/v1/transactions

List recent transactions for the key’s environment

cURL
curl "https://xv9ni4gwk9.execute-api.us-east-1.amazonaws.com/dev/v1/transactions" \
  -H "Authorization: Bearer sk_test_…" \
  -H "X-Tunnel-Origin: https://api.yourapp.com"

Before you charge

Connect a payment provider in the same mode as your key (Test Mode → Paystack/Flutterwave test secrets). Without an enabled provider, create payment returns NO_PROVIDERS.

Next: Create a payment →