Skip to main content

​
Authentication

All requests to the Gale API must be authenticated using a valid API key.

​
Base URL

https://api.withgale.com/v2

​
API Keys

​
Getting Your API Key

  1. Log in to Gale Dashboard
  2. Navigate to Settings → API Keys
  3. Copy your API key
You’ll see two types of keys:
  • Test keys (prefix: glm_test_) - For development and testing
  • Live keys (prefix: glm_live_) - For production

​
Using Your API Key

Include your API key in the Authorization header of every request: 
Authorization: Bearer glm_test_YOUR_API_KEY
Example request: 
curl https://api.withgale.com/v2/products \
  -H "Authorization: Bearer glm_test_YOUR_API_KEY"

​
Authentication Errors

Missing or invalid API keys return a 401 Unauthorized response: 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

​
Idempotency

Prevent duplicate operations by using idempotency keys for state-changing requests.

​
How It Works

Add an Idempotency-Key header to prevent duplicate processing: 
curl -X POST https://api.withgale.com/v2/checkout \
  -H "Authorization: Bearer glm_test_YOUR_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{...}'
  • Key format: Use a unique UUID (v4 recommended)
  • Validity: Keys are stored for 24 hours
  • Behavior: Requests with the same key within 24 hours return the original response without reprocessing

​
When to Use

Use idempotency keys for:
  • Creating checkout sessions (POST /v2/checkout)
  • Creating refunds (POST /v2/refunds)
  • Creating payment links (POST /v2/payment-links)
  • Any POST request that creates or modifies data

​
Best Practices

  • Generate a new UUID for each operation
  • Retry failed requests with the same idempotency key
  • Store the key with your request for retry scenarios
  • Don’t reuse keys across different operations
Example: 
const { v4: uuidv4 } = require('uuid');

const createCheckout = async (data) => {
  const idempotencyKey = uuidv4();

  const response = await fetch('https://api.withgale.com/v2/checkout', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Idempotency-Key': idempotencyKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  return response.json();
};

​
Security Best Practices

  • Never expose API keys in client-side code or public repositories
  • Use environment variables to store API keys
  • Rotate keys regularly in production
  • Use test keys for development and staging environments
  • Monitor API key usage in your dashboard