2. Create API Keys

How API Keys Work

BillStack uses bearer token authentication for external SaaS applications:

• Keys are prefixed with bs_ followed by 48 hex characters (e.g., bs_a1b2c3d4...)
• The raw key is shown once at creation time — store it securely
• Keys are SHA-256 hashed before storage — BillStack never stores the raw key
• Keys can be scoped to specific projects and permissions
• Keys can have optional expiration dates

Create an API Key

Dashboard UI

1. Navigate to Team Settings > API Keys
2. Click Create API Key
3. Enter a name (e.g., "My SaaS Production")
4. Select the project to scope the key to (optional — empty means all projects)
5. Choose scopes (optional — empty means full access)
6. Set an expiration date (optional)
7. Click Create and immediately copy the raw key

API

curl -X POST https://your-billstack.com/api/billstack/teams/{teamId}/api-keys \
  -H "Content-Type: application/json" \
  -H "Cookie: <session-cookie>" \
  -d '{
    "name": "My SaaS Production",
    "projectId": "proj_abc123",
    "scopes": ["customers:read", "customers:write", "subscriptions:read"],
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Response:

{
  "key": {
    "id": "key_xyz789",
    "name": "My SaaS Production",
    "prefix": "bs_a1b2",
    "projectId": "proj_abc123",
    "scopes": ["customers:read", "customers:write", "subscriptions:read"],
    "expiresAt": "2026-12-31T23:59:59Z",
    "createdAt": "2026-03-30T12:00:00Z"
  },
  "rawKey": "bs_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"
}

The rawKey is only returned in this response. Store it immediately.

Using the API Key

Include the key in the Authorization header of all BillStack API requests:

const response = await fetch(
  `${BILLSTACK_URL}/api/billstack/teams/${TEAM_ID}/projects/${PROJECT_ID}/customers`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
  }
);

Available Scopes

Leave the scopes array empty for full access (equivalent to all scopes).

List API Keys

curl https://your-billstack.com/api/billstack/teams/{teamId}/api-keys \
  -H "Cookie: <session-cookie>"

Returns all keys with metadata (the hashed key value is never exposed).

Revoke an API Key

curl -X DELETE https://your-billstack.com/api/billstack/teams/{teamId}/api-keys/{keyId} \
  -H "Cookie: <session-cookie>"

Revocation is immediate — any requests using that key will fail with 401 Unauthorized.

Best Practices

• One key per environment — separate keys for development, staging, production
• Scope keys narrowly — only grant the permissions your app actually needs
• Set expiration dates — rotate keys periodically
• Use environment variables — never hardcode keys in source code
• Rotate before they expire — create a new key, update your app, then revoke the old one

Next Step

With your API key ready, backfill your existing Stripe data into BillStack.