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
- Open the Tunnel dashboard and sign in.
- Make sure the top bar shows Test Mode while you are integrating (switch to Live Mode only for production keys).
- Go to API Keys in the sidebar.
- Click Create API key. Choose a name, environment (
testorlive), and at least one allowed domain (e.g.api.yourapp.com). - 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 onlysk_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| Header | When |
|---|---|
| Authorization | Always — Bearer secret key |
| Content-Type | JSON bodies |
| Idempotency-Key | Recommended on POST /transactions |
| X-Tunnel-Origin | Server 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 →