Skip to main content

​
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
  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: 
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: 
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

Keep your API key secure and never expose it in client-side code or public repositories.
  • 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): 
{
  "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): 
{
  "error": "Sandbox API keys cannot be used in production",
  "code": 401
}
401 Unauthorized (Environment mismatch — production key used in sandbox): 
{
  "error": "Production API keys cannot be used in sandbox",
  "code": 401
}
500 Internal Server Error: 
{
  "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 [email protected].