Authentication

Every request to the BttrForm API must be authenticated with an API key. This guide covers how to create and manage API keys, authenticate requests, understand rate limits, and follow security best practices.

API Key Types

BttrForm provides two types of API keys, each designed for a different stage of development:

Test keys operate against a sandboxed environment. Forms created with a test key do not appear in your production dashboard, and submissions collected in test mode do not count toward your usage limits. This lets you develop and test integrations without affecting your live data.

Creating API Keys

1. Navigate to Settings > API Keys in your BttrForm dashboard.
2. Click Create New Key.
3. Choose Live or Test mode.
4. Give the key a descriptive name (for example, "Backend Server" or "CI Pipeline").
5. Copy the key immediately — it will not be shown again.

You can create up to 10 API keys per account. Each key can be individually revoked without affecting other keys.

Authenticating Requests

Include your API key in the X-API-Key header of every request:

cURL

curl -X GET https://api.bttrlabs.com/v1/forms \
  -H "X-API-Key: bttrform_sk_live_your_key_here"

JavaScript (Fetch)

const response = await fetch('https://api.bttrlabs.com/v1/forms', {
  method: 'GET',
  headers: {
    'X-API-Key': 'bttrform_sk_live_your_key_here',
    'Content-Type': 'application/json'
  }
})

const data = await response.json()
console.log(data)

JavaScript (Axios)

import axios from 'axios'

const client = axios.create({
  baseURL: 'https://api.bttrlabs.com/v1',
  headers: {
    'X-API-Key': process.env.BTTRFORM_API_KEY
  }
})

const { data } = await client.get('/forms')

Python (Requests)

import requests
import os

response = requests.get(
    'https://api.bttrlabs.com/v1/forms',
    headers={'X-API-Key': os.environ['BTTRFORM_API_KEY']}
)

data = response.json()

Authentication Errors

When authentication fails, the API returns one of these error responses:

Missing API Key (401)

{
  "error": "unauthorized",
  "message": "Missing API key. Include your key in the X-API-Key header."
}

Invalid API Key (401)

{
  "error": "unauthorized",
  "message": "Invalid API key. Check that your key is correct and has not been revoked."
}

Revoked API Key (403)

{
  "error": "forbidden",
  "message": "This API key has been revoked. Generate a new key in your dashboard."
}

All error responses follow a consistent structure with an error code and a human-readable message. Your application should check for non-2xx status codes and handle these errors gracefully.

Rate Limits

To ensure fair usage and platform stability, the BttrForm API enforces rate limits based on your subscription tier. Rate limits are applied per API key over a rolling 15-minute window.

Rate Limit Headers

Every API response includes headers that tell you your current rate limit status:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1706792400

Rate Limit Exceeded (429)

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 2026-02-08T12:15:00Z.",
  "retry_after": 47
}

The retry_after field indicates the number of seconds to wait before retrying. Your application should implement exponential backoff or respect the retry_after value rather than immediately retrying.

Handling Rate Limits in Code

Here is a robust pattern for handling rate limits with automatic retry:

async function apiRequest(url, options = {}, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, {
      ...options,
      headers: {
        'X-API-Key': process.env.BTTRFORM_API_KEY,
        'Content-Type': 'application/json',
        ...options.headers
      }
    })

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60', 10)
      console.warn(`Rate limited. Retrying in ${retryAfter}s...`)
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000))
      continue
    }

    if (!response.ok) {
      throw new Error(`API error: ${response.status}`)
    }

    return response.json()
  }

  throw new Error('Max retries exceeded')
}

Test Mode vs. Live Mode

API keys determine which environment your requests target:

• Test keys (bttrform_sk_test_) interact with sandbox data. Use these during development and in your CI/CD pipelines.
• Live keys (bttrform_sk_live_) interact with production data. Use these in your deployed application.

Test mode is fully functional — you can create forms, collect submissions, and test webhooks — without affecting your production data or usage quotas.

Security Best Practices

Follow these practices to keep your API keys secure:

1. Use environment variables — Never hardcode keys in source files. Load them from environment variables or a secrets manager like AWS Secrets Manager, HashiCorp Vault, or Doppler.

2. Restrict key scope — Create separate keys for different services and revoke any key that is no longer needed.

3. Rotate keys regularly — Generate new keys periodically and update your applications. Revoke old keys after confirming the new ones work.

4. Never expose keys client-side — API keys should only be used in server-side code. If you need to call the API from a browser, proxy the request through your backend.

5. Monitor key usage — Check the API Keys section of your dashboard periodically for unexpected usage patterns. If you see requests from unknown IP addresses, revoke the key immediately.

6. Use test keys in CI/CD — Configure your test suites and staging environments to use test keys exclusively.

Next Steps

• Forms API — Create, read, update, and delete forms programmatically.
• Submissions API — Retrieve, filter, and export form submissions via the API.