> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withgale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://dashboard.withgale.com)
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:

```bash theme={null}
Authorization: Bearer glm_test_YOUR_API_KEY
```

**Example request:**

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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:**

```javascript theme={null}
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](/developer-manual/rate-limits) - API request limits
* [Errors](/developer-manual/errors) - Error handling