Authentication

Learn how to authenticate with the Pixlpay API.

API Tokens

All API requests require authentication via API tokens. Tokens are created in your store dashboard.

Creating a Token

1. Go to Settings > API Tokens
2. Click Create Token
3. Configure the token:
   • Name - Descriptive name for identification
   • Scopes - Permissions the token has
4. Click Generate
5. Copy the token immediately - it won't be shown again

Using the Token

Include the token in the Authorization header:

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

Token Scopes

Tokens can be limited to specific permissions:

Scope	Description
products:read	Read product information
products:write	Create and update products
orders:read	Read order data
orders:write	Fulfill and manage orders
customers:read	Read customer data
analytics:read	Access analytics endpoints
webhooks:read	List webhooks
webhooks:write	Create and manage webhooks
discord:agent	Access Discord Agent endpoints for role delivery

Discord Agent Scope

The discord:agent scope is specifically for self-hosted Discord bots. It provides access to:

• GET /api/v1/discord-agent/pending - Fetch pending role operations
• POST /api/v1/discord-agent/claim - Claim operations
• POST /api/v1/discord-agent/confirm/{id} - Confirm completion
• POST /api/v1/discord-agent/fail/{id} - Report failures

See the Discord Agent API Reference for full documentation.

Full Access

Select "Full Access" to grant all permissions. Use this for development but prefer limited scopes in production.

Token Security

Keep Tokens Secret

• Never commit tokens to version control
• Use environment variables
• Don't expose tokens in client-side code
• Rotate tokens periodically

Revoking Tokens

If a token is compromised:

1. Go to Settings > API Tokens
2. Find the token
3. Click Revoke
4. Create a new token

Rate Limits

Each token is rate limited to 60 requests per minute.

Response headers show your current status:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1640000000

When exceeded, you'll receive a 429 Too Many Requests response.

Errors

401 Unauthorized

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

Causes:

• Missing Authorization header
• Invalid token format
• Token revoked or expired
• Token doesn't have required scope

403 Forbidden

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

Cause: Token lacks the scope needed for this endpoint.

Best Practices

1. Use minimal scopes - Only request permissions you need
2. Rotate regularly - Create new tokens periodically
3. Use environment variables - Never hardcode tokens
4. Monitor usage - Track token activity in dashboard
5. Separate tokens - Use different tokens for different integrations