Authenticating Your BillStack API Requests Securely

BillStack uses API keys to authenticate every request you make to the API. You include your secret key in the Authorization header of each call, and BillStack uses it to identify the business, enforce permissions, and scope the request to your account. This page explains how to find your keys, use them correctly, and keep them safe.

Get your API keys

Your API keys live in the BillStack dashboard, one pair per business. To access them:

Sign in to billstack.co.
Open Developer (or Settings → API Keys) in the sidebar.
Select the business you want keys for.

If a business has no keys yet, generate them from this screen. Keys start inactive and must be enabled before they will authenticate requests.

Public and secret keys

Each business has two keys:

Key	Format	Use
Public key	`Bill_Stack-PUB-KEY-…`	Identifies your business in client-side and checkout flows. Safe to use in front-end code.
Secret key	`Bill_Stack-SEC-KEY-…`	Authenticates server-side API calls and verifies webhook signatures. Must stay on your server.

Your secret key is what authenticates API requests. Your public key is used to initialise checkout and identify your business in client-facing contexts - it does not grant access to the API on its own.

Keys are scoped to a single business. If you operate multiple businesses under one BillStack account, each has its own public and secret key pair, and a key only ever acts on the business it belongs to.

Authenticate your requests

Pass your secret key in the Authorization header of every request using the Bearer scheme:

Authorization: Bearer Bill_Stack-SEC-KEY-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Here’s a complete example using curl:

curl -X GET https://api.billstack.co/reserved-accounts \
  -H "Authorization: Bearer Bill_Stack-SEC-KEY-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Every authenticated request to the BillStack API - regardless of HTTP method or endpoint - must include this header. Requests without a valid, active key are rejected immediately.

A newly generated key is inactive until you enable it. If your requests are rejected right after creating a key, confirm the key is enabled in the dashboard.

Use environment variables

Never hardcode your secret key directly in your source code. Store it as an environment variable and read it at runtime. This keeps the key out of your codebase and makes it easy to swap keys without touching your code.

Add your key to a .env file locally and load it with a library like dotenv (Node.js) or python-dotenv (Python). Make sure .env is listed in your .gitignore so it is never committed.

Set the variable in your shell or CI environment:

export BILLSTACK_SECRET_KEY=Bill_Stack-SEC-KEY-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Then reference it in your application code:

const secretKey = process.env.BILLSTACK_SECRET_KEY;

const response = await fetch('https://api.billstack.co/reserved-accounts', {
  headers: {
    'Authorization': `Bearer ${secretKey}`,
    'Content-Type': 'application/json'
  }
});

Keep your keys secret

Your secret key grants access to your BillStack business. Treat it the same way you would treat a password.

Never expose your secret key in client-side code - this includes browser JavaScript, mobile apps, or any code that runs on a device you do not control. Anyone who finds it can make API calls on your behalf. Use the secret key only in server-side code running in a trusted environment. Your public key is the one intended for front-end use.

Follow these practices to protect your keys:

Do not commit keys to source control. Add .env and any secrets files to .gitignore. Use a secrets manager (such as AWS Secrets Manager, HashiCorp Vault, or your platform’s built-in secrets store) in production.
Do not share keys in plain text. Avoid sending keys over email, Slack, or other messaging tools.
Restrict access. Limit which team members and services can view or use your secret key. In BillStack, generating, disabling, and revoking keys is restricted to admins on the business.

Handle authentication errors

If your key is missing, malformed, inactive, or invalid, BillStack returns a 401 Unauthorized response. All BillStack errors share the same shape:

{
  "status": false,
  "message": "Invalid or inactive secret key",
  "data": null
}

Common causes of a 401 error:

Cause	Fix
No `Authorization` header sent	Add `Authorization: Bearer YOUR_SECRET_KEY` to every request
Incorrect header format	Use the `Bearer` scheme exactly: `Bearer Bill_Stack-SEC-KEY-…` - not `Token` or `Basic`
Key copied with extra whitespace	Trim the key before storing or using it
Using the public key to authenticate	Authenticate with the secret key; the public key is for checkout/front-end use
Key is disabled or revoked	Enable the key, or generate a new pair (see below)

Rotate your API keys

Rotate your keys immediately if you suspect they have been compromised or accidentally exposed. In BillStack, rotation is a revoke-then-generate flow: revoking permanently invalidates the current pair, after which you generate a fresh pair.

Go to Developer / API Keys in the dashboard

Navigate to your business’s Developer (or Settings → API Keys) screen in dashboard.billstack.co.

Revoke the current keys

Choose Revoke. For safety, you will be asked to type the business’s public key to confirm. Revoking immediately invalidates both the current public and secret key.

Generate a new pair

Generate a fresh key pair. BillStack displays the new secret key - copy it straight away and store it securely in your secrets manager or environment configuration.

Enable and deploy the new key

Ensure the new key is enabled, update your environment variables or secrets store, and redeploy your application. Verify that your API calls are succeeding before you finish.

Revocation takes effect immediately. Any requests using the old key will fail as soon as it is revoked, so generate, enable, and deploy the new key promptly to avoid downtime.

Getting Started

Webhooks

Reserved Accounts

Transactions

Authenticating Your BillStack API Requests Securely

Get your API keys

Public and secret keys

Authenticate your requests

Use environment variables

Keep your keys secret

Handle authentication errors

Rotate your API keys

​Get your API keys

​Public and secret keys

​Authenticate your requests

​Use environment variables

​Keep your keys secret

​Handle authentication errors

​Rotate your API keys

Get your API keys

Public and secret keys

Authenticate your requests

Use environment variables

Keep your keys secret

Handle authentication errors

Rotate your API keys