​
Overview

Receeco uses a flexible authentication system designed for POS integration. Most endpoints are public to support seamless POS workflows, with optional API key authentication for enhanced security.

​
Authentication Methods

​
Public Access

No authentication required for basic POS operations

​
API Key (Optional)

Enhanced security for production environments

​
Public Endpoints

These endpoints work without authentication to ensure POS systems can operate seamlessly:
  • POST /createReceiptFromPOS - Create digital receipts
  • GET /getReceipt - Retrieve receipt data
  • POST /updateReceiptContact - Update customer contact info
Why Public? POS systems need to create receipts instantly without complex authentication flows that could cause delays or failures during busy periods. For production environments, we recommend using API keys for additional security:

​
Getting Your API Key

  1. Log in to your Merchant Dashboard
  2. Navigate to Settings → API Keys
  3. Generate a new API key
  4. Copy and store it securely
Warning: API keys are sensitive credentials. Store them securely and never commit them to version control.

​
Using API Keys

Include your API key in the Authorization header:

​
cURL Example

curl -X POST https://receeco.com/api/trpc/createReceiptFromPOS \
  -H "Authorization: Bearer pos_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{...}'

​
Node.js Example

const axios = require("axios");

const config = {
  headers: {
    Authorization: "Bearer pos_live_abc123...",
    "Content-Type": "application/json",
  },
};

const response = await axios.post(
  "https://receeco.com/api/trpc/createReceiptFromPOS",
  transactionData,
  config
);

​
Python Example

import requests

headers = {
    'Authorization': 'Bearer pos_live_abc123...',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://receeco.com/api/trpc/createReceiptFromPOS',
    json=transaction_data,
    headers=headers
)

​
API Key Types

​
Test Keys (postest…)

  • Used for development and testing
  • Limited to test transactions
  • No rate limits
  • Safe to use in development environments

​
Live Keys (poslive…)

  • Used for production transactions
  • Full access to all features
  • Rate limited for security
  • Must be kept secure

​
Security Best Practices

​
1. Environment Variables

Store API keys in environment variables, never in code: 
RECEECO_API_KEY=pos_live_abc123...

​
2. Rotate Keys Regularly

Generate new API keys every 90 days and update your systems

​
3. Monitor Usage

Check your dashboard regularly for unusual API activity

​
4. Restrict Access

Only give API keys to systems that need them

​
Rate Limits

API key authentication includes rate limiting for security:
Key TypeRequests per MinuteBurst Limit
TestUnlimitedUnlimited
Live1000100
Tip: Rate limits are per API key. Contact support if you need higher limits for high-volume merchants.

​
Error Handling

Authentication errors return standard HTTP status codes: 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "httpStatus": 401
  }
}

​
Common Authentication Errors

​
401 Unauthorized

  • Invalid or expired API key
  • Missing Authorization header
  • Malformed API key format

​
403 Forbidden

  • API key doesn’t have required permissions
  • Rate limit exceeded
  • Suspended merchant account

​
429 Too Many Requests

  • Rate limit exceeded
  • Too many requests in short time period
  • Implement exponential backoff

​
Migration Guide

​
From Public to API Key Authentication

If you’re currently using public endpoints and want to add API key authentication:
  1. Generate API key in your dashboard
  2. Update your code to include the Authorization header
  3. Test thoroughly in development
  4. Deploy gradually to production

​
Before (Public)

const response = await axios.post(
  "https://receeco.com/api/trpc/createReceiptFromPOS",
  transactionData
);

​
After (API Key)

const response = await axios.post(
  "https://receeco.com/api/trpc/createReceiptFromPOS",
  transactionData,
  {
    headers: {
      Authorization: `Bearer ${process.env.RECEECO_API_KEY}`,
    },
  }
);

​
Testing Authentication

Use our test endpoint to verify your authentication setup: 
curl -X GET https://receeco.com/api/trpc/auth/test \
  -H "Authorization: Bearer pos_test_abc123..."
Success response: 
{
  "result": {
    "data": {
      "authenticated": true,
      "merchantId": "your-merchant-id",
      "keyType": "test"
    }
  }
}
Ready to authenticate! Your API key setup is complete and ready for production use.