Authentication

How to authenticate API requests and ensure safe retries using idempotency keys.

Authentication

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

Base URL

https://api.withgale.com/api/v2

API Keys

Getting Your API Key

1. Log in to Gale Dashboard
2. Navigate to Developer Tools → API Keys
3. Select Generate API Key, give the key a name, and select Generate Key
4. Copy the key from the dialog and store it securely

The full key is displayed only once, at the moment you generate it. The API Keys table shows a truncated value that cannot be used to authenticate. If you lose a key, revoke it and generate a new one.

Keys are scoped to the environment you’re in when you generate them, and the table only lists keys for the environment you’re currently viewing. Use the Test Mode toggle in the top bar to switch.

• Test keys (prefix: glm_test_) - Generated with Test Mode on. For development and testing
• Live keys (prefix: glm_live_) - Generated with Test Mode off. For production

Live keys become available once account verification is complete. A key looks like glm_live_<token_id>.<secret>.

To disable a key, open the ⋮ menu beside it and select Revoke Key. Revoking takes effect immediately and breaks every integration using that key.

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/api/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/api/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 /api/v2/checkout)
• Creating refunds (POST /api/v2/refunds)
• Creating payment links (POST /api/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/api/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

Related

• Rate Limits - API request limits
• Errors - Error handling