> ## Documentation Index
> Fetch the complete documentation index at: https://docs.billstack.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticating Your BillStack API Requests Securely

> Learn how to find, use, and protect your BillStack API keys - including public vs. secret keys, the Authorization header, environment variables, and key rotation.

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:

1. Sign in to [billstack.co](https://billstack.co).
2. Open **Developer** (or **Settings → API Keys**) in the sidebar.
3. 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.

<Info>
  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.
</Info>

## Authenticate your requests

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

```http theme={null}
Authorization: Bearer Bill_Stack-SEC-KEY-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Here's a complete example using `curl`:

```bash theme={null}
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.

<Note>
  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.
</Note>

## 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.

<Tip>
  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.
</Tip>

Set the variable in your shell or CI environment:

```bash theme={null}
export BILLSTACK_SECRET_KEY=Bill_Stack-SEC-KEY-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Then reference it in your application code:

```javascript theme={null}
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.

<Warning>
  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.
</Warning>

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:

```json theme={null}
{
  "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.

<Steps>
  <Step title="Go to Developer / API Keys in the dashboard">
    Navigate to your business's **Developer** (or **Settings → API Keys**) screen in [dashboard.billstack.co](https://billstack.co).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>