Authentication

All API requests must be authenticated using an API key. You can obtain your API key from the Caramel Dashboard.

Authentication Methods

Caramel supports two authentication methods:

Bearer Token

Recommended - Pass your API key in the Authorization header

Authorization: Bearer YOUR_API_KEY

API Key Header

Alternative method using a custom header

X-Caramel-API-Key: YOUR_API_KEY

Quick Start

1. Get your API key

   Log in to your Caramel Dashboard and navigate to Settings → API Keys

2. Choose your environment

   • Production: pk_live_... for real transactions
   • Test: pk_test_... for development and testing

3. Make your first request

   cURL

   curl https://api.joincaramel.com/v1/gift-cards \
     -H "Authorization: Bearer pk_live_YOUR_API_KEY" \
     -H "Content-Type: application/json"

   JavaScript

   const response = await fetch('https://api.joincaramel.com/v1/gift-cards', {
     headers: {
       'Authorization': 'Bearer pk_live_YOUR_API_KEY',
       'Content-Type': 'application/json'
     }
   });

   Python

   import requests
   
   response = requests.get(
     'https://api.joincaramel.com/v1/gift-cards',
     headers={
       'Authorization': 'Bearer pk_live_YOUR_API_KEY',
       'Content-Type': 'application/json'
     }
   )

   PHP

   $ch = curl_init('https://api.joincaramel.com/v1/gift-cards');
   curl_setopt($ch, CURLOPT_HTTPHEADER, [
     'Authorization: Bearer pk_live_YOUR_API_KEY',
     'Content-Type: application/json'
   ]);
   $response = curl_exec($ch);

API Key Types

Key Type	Prefix	Usage	Capabilities
Production	pk_live_	Live transactions	Full access to all API endpoints
Test	pk_test_	Development & testing	Full access, no real charges
Restricted	rk_live_	Limited scope	Custom permissions per key
Publishable	pub_live_	Client-side	Read-only operations

Caution

Never expose your secret API keys in client-side code or public repositories. Use publishable keys for client-side operations.

SDK Authentication

Our official SDKs handle authentication automatically:

Node.js

import { Caramel } from '@caramel/node';

const caramel = new Caramel({
  apiKey: process.env.CARAMEL_API_KEY,
  // Optional: defaults to production
  environment: 'production'
});

// SDK handles authentication headers automatically
const giftCards = await caramel.giftCards.list();

Python

from caramel import Caramel
import os

caramel = Caramel(
  api_key=os.environ.get('CARAMEL_API_KEY'),
  environment='production'  # Optional
)

# Authentication handled automatically
gift_cards = caramel.gift_cards.list()

Ruby

require 'caramel'

Caramel.api_key = ENV['CARAMEL_API_KEY']
Caramel.environment = :production  # Optional

# Authentication handled automatically
gift_cards = Caramel::GiftCard.list

PHP

<?php
require_once 'vendor/autoload.php';

$caramel = new \Caramel\Client([
  'api_key' => $_ENV['CARAMEL_API_KEY'],
  'environment' => 'production'  // Optional
]);

// Authentication handled automatically
$giftCards = $caramel->giftCards->list();

OAuth 2.0 Coming Soon

For partners and marketplace integrations, we support OAuth 2.0 authentication flow.

Authorization Flow

sequenceDiagram
    participant User
    participant YourApp
    participant Caramel

    User->>YourApp: Initiate connection
    YourApp->>Caramel: Redirect to /oauth/authorize
    Caramel->>User: Show consent screen
    User->>Caramel: Approve access
    Caramel->>YourApp: Redirect with auth code
    YourApp->>Caramel: Exchange code for token
    Caramel->>YourApp: Return access token
    YourApp->>Caramel: Make API requests

Scopes

Define the level of access your application needs:

• read:gift_cards - View gift cards
• write:gift_cards - Create and manage gift cards
• read:customers - View customer data
• write:customers - Manage customers
• read:analytics - Access analytics data
• admin - Full account access

Security Best Practices

Rotate Keys Regularly

Rotate your API keys every 90 days to maintain security

Use Environment Variables

Never hardcode API keys. Store them in environment variables

Implement Rate Limiting

Respect rate limits to avoid service interruption

Monitor Usage

Regularly review API usage logs for suspicious activity

Rate Limiting

API requests are rate limited to ensure fair usage:

Plan	Requests per Second	Requests per Day
Free	10 req/s	10,000 req/day
Starter	50 req/s	100,000 req/day
Professional	100 req/s	1,000,000 req/day
Enterprise	Custom	Unlimited

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Error Handling

Authentication errors return appropriate HTTP status codes:

Status Code	Error Type	Description
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid key but insufficient permissions
429	Too Many Requests	Rate limit exceeded

Example error response:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided",
    "code": "invalid_api_key",
    "doc_url": "https://docs.joincaramel.com/errors/invalid_api_key"
  }
}

Testing Authentication

Use our test endpoint to verify your authentication:

curl https://api.joincaramel.com/v1/auth/verify \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response:

{
  "authenticated": true,
  "key_type": "live",
  "permissions": ["read", "write"],
  "restaurant": {
    "id": "rest_1234",
    "name": "Your Restaurant"
  }
}

Webhook Signatures

For webhook endpoints, verify the signature to ensure requests come from Caramel:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Tip

Find your webhook signing secret in the Webhook Settings page.

Next Steps

Now that you’re authenticated, you can:

• Create your first gift card
• List customers
• Set up webhooks
• View analytics

Need Help?

API Status

Check current API status and incidents

status.joincaramel.com

Support

Contact our API support team

api@joincaramel.com