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

# Authentication

> Learn how to authenticate your API v2 requests

## API Key Authentication

The Pure API v2 uses API key authentication for all requests. You'll need to include your API key in the `x-api-key` header with every request.

### Getting Your API Key

To obtain an API key for the v2 API:

1. Go to your [API Keys dashboard](https://www.collectpure.com/dashboard/api-keys)
2. Click **Create API Key**
3. Choose an environment:
   * **Live** — real transactions against the production API (`https://api.collectpure.com`)
   * **Sandbox** — test transactions with no real money (`https://sandbox.api.collectpure.com`)
4. Choose a permission level:
   * **Read Only** — view data only
   * **Admin** — full API access (required for the Execution API)

### Using Your API Key

Include your API key in the `x-api-key` header of all requests:

```bash theme={null}
curl -H "x-api-key: your-api-key-here" \
     https://api.collectpure.com/v1/products
```

### Example Request

Here's a complete example of an authenticated request:

```bash theme={null}
curl -X GET \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  https://api.collectpure.com/v1/products
```

### Testing Your API Key

You can test if your API key is working by making a request to any protected endpoint. If your key is valid, you'll receive the requested data. If invalid, you'll receive a 401 Unauthorized response.

### Security Best Practices

<Warning>
  Keep your API key secure and never expose it in client-side code or public
  repositories.
</Warning>

* Store your API key in environment variables
* Use HTTPS for all API requests
* Rotate your API key regularly
* Monitor your API usage for any suspicious activity

### Environment enforcement

API keys are bound to a specific environment. The API rejects requests when there is a mismatch between the key's environment and the target API:

* **Sandbox keys** (`sandbox`) can only be used against the sandbox API (`https://sandbox.api.collectpure.com`). Using a sandbox key against the production API returns an error.
* **Live keys** (`live`) can only be used against the production API (`https://api.collectpure.com`). Using a live key against the sandbox API returns an error.

Make sure you are using the correct key for the environment you are targeting.

### Error Responses

If authentication fails or an error occurs, you'll receive a JSON response with the following format:

**401 Unauthorized (Invalid API Key):**

```json theme={null}
{
  "error": "Unknown API key: {KEY THAT WAS SENT}",
  "code": 401,
  "suggestion": "Please check your API key and try again"
}
```

**401 Unauthorized (Environment mismatch — sandbox key used in production):**

```json theme={null}
{
  "error": "Sandbox API keys cannot be used in production",
  "code": 401
}
```

**401 Unauthorized (Environment mismatch — production key used in sandbox):**

```json theme={null}
{
  "error": "Production API keys cannot be used in sandbox",
  "code": 401
}
```

**500 Internal Server Error:**

```json theme={null}
{
  "error": "Internal Server Error",
  "code": 500,
  "suggestion": "Please try again later. If the problem persists, please contact support."
}
```

Common error responses include:

* `401 Unauthorized`: Invalid or missing API key
* `401 Unauthorized`: API key environment does not match the target API environment
* `403 Forbidden`: Valid API key but insufficient permissions
* `500 Internal Server Error`: Server-side error occurred

## Support

If you need help with authentication or have questions about your API key, please contact our support team at [support@collectpure.com](mailto:support@collectpure.com).