Authentication & API Keys

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

curl -H "Authorization: Bearer bag_test_sk_your_key_here" \
  https://justusebag.xyz/api/payment-links

API key types

Bag 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 Bag 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

With the TypeScript SDK

The SDK handles the Authorization header for you:

import { Bag } from "@getbagsapp/sdk";

const bag = new Bag({
  apiKey: process.env.BAG_API_KEY!,
});

With raw HTTP

Include the key as a Bearer token:

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

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 Bag 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, Bag 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

What's next