Authentication

The Givebutter API uses Bearer token authentication to secure all API requests. Authentication is required for every API call and ensures that only authorized applications can access your fundraising data.

Quick Start

Include your API key in the Authorization header of every request:

curl https://api.givebutter.com/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY"

Getting Your API Key

Log into Dashboard

Navigate to API Settings

Go to Settings > Integrations > API Keys

Generate API Key

Click Create New API Key and give it a descriptive name (e.g., “Production CRM Integration”)

Copy & Store Securely

Copy your API key immediately - you won’t be able to see it again. Store it securely in your password manager or environment variables.

Important: Your API key is shown only once at creation. If you lose it, you’ll need to generate a new one. Never share your API key or commit it to version control.

API Key Types

Givebutter provides different types of API keys for different environments:

Test Keys

Test API keys allow you to build and test your integration without affecting production data.

Prefix: test_
Use Case: Development, testing, staging environments
Data Access: Test mode data only
Safety: Transactions won’t affect real donors or bank accounts

bash Example Test Key test_sk_abc123def456ghi789jkl012mno345

Live Keys

Live API keys access your production Givebutter account and real fundraising data.

Prefix: live_
Use Case: Production applications
Data Access: Real campaigns, donors, and transactions
Safety: Use with caution - affects real data

bash Example Live Key live_sk_xyz789abc456def123ghi890jkl567

Always start development with test keys. Only switch to live keys when you’re ready to deploy to production.

Authentication Flow

Include API Key in Header

Add the Authorization header with Bearer YOUR_API_KEY to your request

API Validates Key

Givebutter validates your API key and checks permissions

Request Processed

If valid, your request is processed and a response is returned

Error if Invalid

If invalid, you receive a 401 Unauthorized error response

Testing Your Authentication

Verify your API key is working correctly with a simple test request:

curl https://api.givebutter.com/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -v

Security Best Practices

Never Expose API Keys in Client-Side Code

Don’t do this:

// ❌ WRONG - API key exposed in browser
const apiKey = 'live_sk_abc123...';
fetch('https://api.givebutter.com/v1/campaigns', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

Do this instead:

// ✅ CORRECT - Call your backend API
fetch('https://yourapp.com/api/campaigns', {
  headers: { 'Authorization': `Bearer ${userSessionToken}` }
});

Your backend should securely store the Givebutter API key and make requests on behalf of users.

Use Environment Variables

Store API keys in environment variables, never in code:

.env

GIVEBUTTER_API_KEY=live_sk_abc123def456...
GIVEBUTTER_TEST_API_KEY=test_sk_xyz789abc456...

Then access them in your code:

const apiKey = process.env.GIVEBUTTER_API_KEY;

import os
api_key = os.getenv('GIVEBUTTER_API_KEY')

Add .env to .gitignore

Prevent accidentally committing secrets to version control:

.gitignore

.env
.env.local
.env.production
*.pem
*.key

Rotate API Keys Regularly

Best practice is to rotate API keys every 90 days:

Generate a new API key in your Dashboard
Update your production environment variables
Deploy the change
Verify everything works
Delete the old API key

This limits exposure if a key is ever compromised.

Use Separate Keys for Each Environment

Create different API keys for each environment:

Development: dev_integration
Staging: staging_integration
Production: prod_integration

This makes it easier to rotate keys and track usage per environment.

Implement Key Management

For enterprise applications, use a secrets manager:

AWS Secrets Manager
HashiCorp Vault
Azure Key Vault
Google Secret Manager

These services provide:

Automatic rotation
Access logging
Encryption at rest
Fine-grained access control

Monitor API Key Usage

Regularly review API logs in your Givebutter Dashboard:

Check for unusual request patterns
Monitor failed authentication attempts
Track API usage by key
Set up alerts for suspicious activity

Authentication Errors

401 Unauthorized

Your API key is missing, invalid, or revoked.

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided",
    "code": 401
  }
}

Common causes:

API key is missing from the request
API key is incorrect or has typos
API key has been revoked
Using Authorization: YOUR_API_KEY instead of Authorization: Bearer YOUR_API_KEY

How to fix:

Verify your API key is correct
Ensure you’re using the Bearer prefix
Check if the key was revoked in your Dashboard
Generate a new API key if needed

403 Forbidden

Your API key is valid but lacks permission for this resource.

{
  "error": {
    "type": "permission_error",
    "message": "Your API key does not have permission to access this resource",
    "code": 403
  }
}

Common causes:

API key has restricted permissions
Trying to access another organization’s data
Resource has been archived or deleted

How to fix:

Check API key permissions in Dashboard
Verify you’re accessing the correct organization’s resources
Ensure the resource exists and is active

HTTPS Requirement

All API requests must use HTTPS. Requests made over plain HTTP will fail immediately.

The Givebutter API rejects all non-HTTPS requests to protect your API keys and data in transit.

curl http://api.givebutter.com/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY"

# Error: Connection refused

API Key Management

Viewing Active Keys

In your Dashboard under Settings > API Keys, you can:

View all active API keys
See when each key was created
See when each key was last used
View the key name and description

For security, only the first few and last few characters of each key are visible.

Revoking Keys

If an API key is compromised or no longer needed:

Go to Settings > API Keys
Find the key you want to revoke
Click Revoke or Delete
Confirm the action

Revoking a key immediately invalidates it. Any applications using that key will stop working. Update your applications with a new key before revoking the old one.

Key Naming Best Practices

Give your API keys descriptive names:

✅ “Production Salesforce Integration”
✅ “Staging Environment - Testing”
✅ “Mobile App v2.0”
❌ “Key 1”
❌ “test”

Good names help you:

Identify which keys are used where
Decide which keys to rotate
Track down issues faster

Common Authentication Patterns

Server-to-Server

Most secure: API calls from your backend server.

// Backend API route
app.get('/api/campaigns', async (req, res) => {
  // Authenticate user first
  const user = await authenticateUser(req);

  // Use server-stored API key
  const response = await fetch('https://api.givebutter.com/v1/campaigns', {
    headers: {
      Authorization: `Bearer ${process.env.GIVEBUTTER_API_KEY}`,
    },
  });

  const campaigns = await response.json();
  res.json(campaigns);
});

Webhook Handlers

Authenticate incoming webhooks from Givebutter:

app.post('/webhooks/givebutter', async (req, res) => {
  // Verify webhook signature (when available)
  const signature = req.headers['x-givebutter-signature'];

  // Process webhook event
  const event = req.body;

  // Optionally fetch more data from API
  const response = await fetch(
    `https://api.givebutter.com/v1/transactions/${event.transaction_id}`,
    {
      headers: {
        Authorization: `Bearer ${process.env.GIVEBUTTER_API_KEY}`,
      },
    },
  );

  res.json({ received: true });
});

Background Jobs

For scheduled tasks and batch processing:

import os
import schedule
import requests

def sync_donations():
    """Sync donations from Givebutter to our database"""
    api_key = os.getenv('GIVEBUTTER_API_KEY')
    headers = {'Authorization': f'Bearer {api_key}'}

    response = requests.get(
        'https://api.givebutter.com/v1/transactions',
        headers=headers,
        params={'created_after': get_last_sync_time()}
    )

    transactions = response.json()['data']
    save_to_database(transactions)

# Run every hour
schedule.every().hour.do(sync_donations)

Troubleshooting

Getting 401 errors despite correct key

Check for these common issues:

Extra spaces before or after the API key
Missing “Bearer ” prefix
Incorrect header name (should be Authorization)
API key from wrong environment (test vs live)
Key was revoked in Dashboard

Works in curl but not in code

Common causes:

HTTP client not sending headers correctly
Headers being stripped by middleware
CORS issues (if calling from browser)
API key not loaded from environment variables

Test with verbose logging to see exact headers sent.

Intermittent authentication failures

Possible causes:

Using multiple API keys and one is invalid
Load balancer not forwarding headers
API key rotation in progress
Connection being intercepted by proxy

Check logs for patterns in failures.

Next Steps

Make Your First Request

Try fetching your campaigns

Error Handling

Learn about error codes

Rate Limits

Understand rate limiting

Pagination

Work with paginated results

Need Help?

If you’re having trouble with authentication:

Double-check your API key is correct
Verify you’re using the Bearer prefix
Test with curl to isolate the issue
Check the API Status Page
Contact [email protected] with:
- The first/last 4 characters of your API key
- Example request that’s failing
- Error messages you’re receiving
- Programming language and HTTP library used

Getting Started

Resources

Quick Start

Getting Your API Key

API Key Types

Test Keys

Live Keys

Authentication Flow

Testing Your Authentication

Security Best Practices

Authentication Errors

401 Unauthorized

403 Forbidden

HTTPS Requirement

API Key Management

Viewing Active Keys

Revoking Keys

Key Naming Best Practices

Common Authentication Patterns

Server-to-Server

Webhook Handlers

Background Jobs

Troubleshooting

Next Steps

Make Your First Request

Error Handling

Rate Limits

Pagination

Need Help?

Getting Started

Resources

​Quick Start

​Getting Your API Key

​API Key Types

​Test Keys

​Live Keys

​Authentication Flow

​Testing Your Authentication

​Security Best Practices

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​HTTPS Requirement

​API Key Management

​Viewing Active Keys

​Revoking Keys

​Key Naming Best Practices

​Common Authentication Patterns

​Server-to-Server

​Webhook Handlers

​Background Jobs

​Troubleshooting

​Next Steps

Make Your First Request

Error Handling

Rate Limits

Pagination

​Need Help?

Quick Start

Getting Your API Key

API Key Types

Test Keys

Live Keys

Authentication Flow

Testing Your Authentication

Security Best Practices

Authentication Errors

401 Unauthorized

403 Forbidden

HTTPS Requirement

API Key Management

Viewing Active Keys

Revoking Keys

Key Naming Best Practices

Common Authentication Patterns

Server-to-Server

Webhook Handlers

Background Jobs

Troubleshooting

Next Steps

Need Help?