Authentication & API Keys

Every request to the Bags API requires a Bearer token in the Authorization header. Bags uses API keys — no OAuth, no sessions, no cookies.

curl -H "Authorization: Bearer bag_test_sk_your_key_here" \
  https://www.getbags.app/api/payment-links

API key types

Bags issues two types of keys. Both work identically — the only difference is which environment they hit.

Test keys are available immediately after signup. Use them for all development and testing.

Live keys require KYB verification. You can't generate a live key until your business is approved.

Generate an API key

1. Sign in to the Bags dashboard.
2. Go to Developer Settings.
3. Click Create API Key.
4. Choose Test or Live (live requires KYB approval).
5. Copy the key immediately — it's shown once and cannot be retrieved later.

Store it as an environment variable:

export BAG_API_KEY="bag_test_sk_your_key_here"

Using the key

Bags is a plain REST API — send the key as a Bearer token on every request. Every example in these docs uses the language's native HTTP client.

curl -X POST https://www.getbags.app/api/payment-links \
  -H "Authorization: Bearer $BAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pro Plan", "amount": 29.99, "network": "base_sepolia"}'

const response = await fetch("https://www.getbags.app/api/payment-links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BAG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Pro Plan",
    amount: 29.99,
    network: "base_sepolia",
  }),
});

const result = await response.json();

import os
import requests

response = requests.post(
    "https://www.getbags.app/api/payment-links",
    headers={
        "Authorization": f"Bearer {os.environ['BAG_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Pro Plan",
        "amount": 29.99,
        "network": "base_sepolia",
    },
)

result = response.json()

Key security

• Never commit keys to version control. Use environment variables or a secrets manager.
• Never expose keys in client-side code. API keys are server-side only. If you need to call Bags from a browser, proxy through your backend.
• Rotate keys if compromised. Delete the old key in the dashboard and create a new one. There's no downtime — old and new keys can coexist until you delete the old one.

Error responses

If authentication fails, Bags returns a 401:

{
  "status": "error",
  "message": "Invalid or missing API key",
  "code": "UNAUTHORIZED"
}

Common causes:

• Missing Authorization header
• Malformed key (check for trailing whitespace)
• Using a test key against a live-only endpoint (or vice versa)
• Key was deleted from the dashboard

Dashboard-only routes

Some endpoints require a dashboard session (Supabase cookie), not an API key:

Merchant integrations should use API keys for catalog, checkouts, transactions, and settlement balance/payout. Register webhooks in the dashboard; verify deliveries with whsec_* secrets.

What's next