Authentication

All Pixlpay API requests require authentication using Bearer tokens. This guide explains how authentication works and best practices for securing your integrations.

Bearer Token Authentication

Include your API token in the Authorization header of every request:

curl https://yourstore.pixlpay.net/api/external/v1/products \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication
Accept	Recommended	Should be application/json
Content-Type	For POST/PUT	Should be application/json

Example Request

curl -X POST https://yourstore.pixlpay.net/api/external/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhook", "events": ["order.paid"]}'

API Scopes

API tokens have granular scopes that control what resources they can access:

Available Scopes

Scope	Description
products:read	View products and inventory
products:write	Create, update, delete products
orders:read	View order details
orders:write	Fulfill orders, update status
customers:read	View customer profiles
customers:write	Update customer information
analytics:read	Access revenue and sales data
webhooks:read	View webhook endpoints
webhooks:write	Manage webhook endpoints
settings:read	View store settings
settings:write	Update store settings

Scope Errors

If your token lacks the required scope, you'll receive a 403 error:

{
  "success": false,
  "error": "Forbidden",
  "message": "Token does not have the required scope: orders:write"
}

Error Responses

401 Unauthorized

Token is missing, invalid, or revoked:

{
  "success": false,
  "error": "Unauthorized",
  "message": "Invalid or missing API token"
}

Common causes:

• Missing Authorization header
• Typo in the token
• Token has been revoked
• Token has expired

403 Forbidden

Token is valid but lacks required permissions:

{
  "success": false,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Common causes:

• Token doesn't have the required scope
• Attempting to access another tenant's resources

Security Best Practices

Token Storage

Never expose tokens

• Never commit tokens to version control
• Never expose tokens in client-side code
• Never log tokens in plain text

Recommended practices:

• Store tokens in environment variables
• Use secrets management (AWS Secrets Manager, HashiCorp Vault, etc.)
• Encrypt tokens at rest

# Good: Environment variable
export PIXLPAY_API_TOKEN="your_token_here"

# In your code
token = os.environ.get('PIXLPAY_API_TOKEN')

Token Rotation

Regularly rotate your tokens to minimize security risks:

1. Create a new token with the same scopes
2. Update your application to use the new token
3. Verify the new token works correctly
4. Revoke the old token

Minimum Permissions

Follow the principle of least privilege:

• Only request scopes your integration actually needs
• Create separate tokens for different integrations
• Use read-only tokens when write access isn't needed

Monitor Token Usage

• Review API logs regularly for unusual activity
• Set up alerts for failed authentication attempts
• Track which endpoints each token accesses

Code Examples

PHP

<?php

$token = getenv('PIXLPAY_API_TOKEN');

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://yourstore.pixlpay.net/api/external/v1/products');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Accept: application/json',
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 401) {
    throw new Exception('Authentication failed');
}

$data = json_decode($response, true);

Node.js

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://yourstore.pixlpay.net/api/external/v1',
  headers: {
    'Authorization': `Bearer ${process.env.PIXLPAY_API_TOKEN}`,
    'Accept': 'application/json',
  },
});

async function getProducts() {
  try {
    const response = await client.get('/products');
    return response.data;
  } catch (error) {
    if (error.response?.status === 401) {
      throw new Error('Authentication failed');
    }
    throw error;
  }
}

Python

import os
import requests

class PixlpayClient:
    def __init__(self):
        self.base_url = 'https://yourstore.pixlpay.net/api/external/v1'
        self.token = os.environ.get('PIXLPAY_API_TOKEN')

    def _headers(self):
        return {
            'Authorization': f'Bearer {self.token}',
            'Accept': 'application/json',
        }

    def get_products(self):
        response = requests.get(
            f'{self.base_url}/products',
            headers=self._headers()
        )

        if response.status_code == 401:
            raise Exception('Authentication failed')

        return response.json()

Related

• API Tokens - Creating and managing tokens
• Error Handling - Handling API errors