API keys and authentication

Every request to the Bachs API carries a secret key in the Authorization header. The key tells Bachs which organization is calling and which environment the request belongs to: the sandbox, where charges are simulated, or production, where real money moves. Create a sandbox key first. A production key only works once your account is verified.

Two environments, two keys

	Sandbox	Production
Key prefix	`sk_sandbox_`	`sk_live_`
Base URL	`https://sandbox-api.bachs.io`	`https://api.bachs.io`
Money	Simulated. No real charge is made.	Real. Charges go to payment providers.
Available	As soon as you sign up	After account verification

A key only works against its own environment, so a sandbox key sent to the production URL is rejected. The two environments share nothing: not customers, not balances, not webhook endpoints. See Test your integration.

Create a key

Keys live in the Developer Portal, under API keys. The form asks for two things: a name, and the scopes the key is allowed to use. Switch to the sandbox before you start, so the key you create is a sandbox key.

Open API keys and click Create secret key

From any page of the dashboard, click Developer Portal at the bottom left of the sidebar, then the API keys tab.

Name the key and choose its scopes

Name it after the thing that will use it, such as checkout-server or production-webhook, so you can tell keys apart later. Then tick only the scopes it needs. A key cannot reach an endpoint outside its scopes, so a leaked key can do less damage.

Copy the key

The full key is shown once, right after you create it. Put it in a secrets manager or an environment variable before you close the dialog. There is no way to see it again; if you lose it, rotate the key to get a new one.

Scopes

A scope is <resource>:<action>, where the action is read or write. The dashboard shows them as labels, such as View payments for payments:read and Create & charge for payments:write. Leaving Select all checked creates a key that can do anything your organization can.

Resource	`read`	`write`
`payments`	Read and list payments	Create checkouts and charge
`customers`	Read and list customers	Create and update customers
`products`	Read and list products	Create, update and archive products
`refunds`	Read and list refunds	Issue refunds
`disputes`	Read and list disputes	Submit evidence and manage disputes
`payouts`	Read payouts and destinations	Create destinations and start payouts
`webhooks`	Read endpoints and events	Create and change endpoints, rotate secrets, resend events

A request to an endpoint outside the key’s scopes gets a 403 Forbidden. Every endpoint’s page in the API reference names the scope it needs, and Permissions lists them all.

Send your first request

Send the key as a Bearer token. This lists the products in your sandbox:

curl https://sandbox-api.bachs.io/v1/products \
  -H "Authorization: Bearer $BACHS_API_KEY" \
  -H "Accept: application/json"

const response = await fetch("https://sandbox-api.bachs.io/v1/products", {
  headers: { Authorization: `Bearer ${process.env.BACHS_API_KEY}` },
});
const { items } = await response.json();

import os
import requests

response = requests.get(
    "https://sandbox-api.bachs.io/v1/products",
    headers={"Authorization": f"Bearer {os.environ['BACHS_API_KEY']}"},
)
items = response.json()["items"]

If the key works, the response is a 200 with your products in items and a pagination block. A product looks like this:

Response

{
  "items": [
    {
      "id": "prod_1a2b3c4d5e6f7g8h",
      "name": "Pro Plan",
      "price": { "currency": "USD", "price_type": "fixed", "amount": "29.00" },
      "billing_cycle": { "interval": "month", "frequency": 1 },
      "status": "active",
      "created_at": "2026-07-13T14:00:00.000Z"
    }
  ],
  "pagination": { "has_more": false, "limit": 20, "returned": 1, "total": 1 }
}

A 401 Unauthorized means the key is missing, wrong, or belongs to the other environment. A 403 Forbidden means the key is valid but lacks the scope. Amounts are decimal strings in the currency’s own units, so "29.00" is twenty-nine dollars. The official Node.js and Python SDKs take the key once when you create the client and add the header for you.

Keep keys safe

A secret key can move money, so treat it like a password.

Server only. Never put a key in browser JavaScript, a mobile app or anything you ship to users, because anyone can read it there. The overlay checkout needs no key in the browser.
Environment variables or a secrets manager, never source control, logs, screenshots or support tickets.
Least scope. Grant only what the integration uses. A key for a product sync does not need payments:write.
Sandbox keys while you build. Swap to a live key when you go live, and never mix the two in one deployment.
Rotate when in doubt. If a key may have leaked, or the service that used it is gone, rotate it. Rotation invalidates the old secret at once, so update the deployment first. Revoke a key only when you are sure nothing uses it.

Next steps

Set up your development environment: put the key to work with the CLI and an SDK.
Test your integration: what the sandbox simulates and how to force a failed payment.
API keys in the Developer Portal: rotating, revoking, editing scopes and the per-key request chart.

Overview

Start building

Common use cases

More resources