Tracepos Developer HubTracepos Developer Hub
Home
Guide
POS & Integrations
API Reference
Webhooks
Postman Collection
Home
Guide
POS & Integrations
API Reference
Webhooks
Postman Collection
  • Getting Started

    • Getting Started
    • Authentication & Security Scopes
    • Postman Collection
    • Architecture & Core Concepts
    • Security & Best Practices
    • Deployment & Hosting Guide

Authentication & Security Scopes

All requests to the Tracepos Public API are authenticated using the Enterprise Dual-Key System. This model provides secure, stateless authentication while strictly enforcing one-way secret hashing, tenant-warehouse binding, per-key rate limiting, and granular permission scopes.


Dual-Key Architecture

Unlike platforms that use a single global token, Tracepos separates identity from cryptographic secret verification:

Tracepos Hardened Public API Security & Scope Pipeline

1. X-Tracepos-Public-Key

  • Prefix: Trp-pk-...
  • Purpose: Identifies your integration client, verifies key status and expiration, and resolves the warehouse branch context.
  • Exposure: Safe to store in device configuration files or environment variables.

2. X-Tracepos-Secret-Key

  • Prefix: Trp-sk-...
  • Purpose: Cryptographically authenticates the caller against a one-way hashed credential.
  • Storage: Stored in the Tracepos database using one-way cryptographic hashing (Hash::make() / Hash::check()). Secrets are never stored in plaintext or reversible encryption.
  • Display-Once Policy: Secrets are displayed only once at the time of key creation. Once the dialog is closed, the secret cannot be revealed or recovered. Store it immediately in a secure secrets manager.
  • Exposure: Strictly Confidential. Must only be kept in backend environment variables, server keystores, or hardware security modules (HSM). Never embed in frontend JavaScript bundles or public repositories.

Required Request Headers

Every API request requires both authentication headers:

Accept: application/json
Content-Type: application/json
X-Tracepos-Public-Key: <public-key>
X-Tracepos-Secret-Key: <secret-key>
HeaderTypeDescriptionExample
X-Tracepos-Public-KeyStringYour warehouse Public KeyTrp-pk-9b4f2c018a...
X-Tracepos-Secret-KeyStringYour warehouse Secret KeyTrp-sk-e72d8a55c1...
AcceptStringMust always be JSONapplication/json
Content-TypeStringRequired for POST, PUT, PATCH requestsapplication/json

Permission Scopes (RBAC)

Every API key must have one or more assigned scopes. The RequirePublicApiScope middleware checks the key's authorized scopes before allowing route execution:

ScopePermission LevelCovered Operations
readRead-OnlyAll GET discovery, list, and detail endpoints (products, categories, brands, warehouses, customers, suppliers, sales, purchases, payments, expenses, returns, payment-modes).
writeTransactionalCreation of operational records: POST /customers, POST /suppliers, POST /sales, POST /purchases, POST /payments, POST /expenses, POST /expenses/{id}/payments, POST /sales-returns, POST /purchase-returns.
inventoryStock & Pricing ControlStock and price modifications: POST /stock-adjustments and POST /price-adjustments.

If an authenticated key attempts to execute a route without the required scope, Tracepos denies the request with HTTP 403 Forbidden:

{
  "status": "error",
  "message": "API key does not have the required permission."
}

Per-Key Rate Limiting

Rate limiting is tracked and enforced independently for each authenticated API key using Laravel's Cache Rate Limiter:

  • Default Limit: 60 requests per minute.
  • Configurable: Limits can be customized per key in the Tracepos administrator settings.
  • Throttling Response: Exceeding the rate limit returns HTTP 429 Too Many Requests:
{
  "status": "error",
  "message": "API rate limit exceeded."
}

Uniform Authentication Error (HTTP 401)

To protect against timing attacks, username/key enumeration, and security probing, Tracepos returns an identical, uniform HTTP 401 Unauthorized response for all authentication failures:

{
  "status": "error",
  "message": "Invalid API credentials."
}

This uniform response is returned when:

  • Either the X-Tracepos-Public-Key or X-Tracepos-Secret-Key header is missing or empty.
  • The public key does not exist or is inactive (status != 1).
  • The API key has expired (expires_at in the past).
  • The secret key does not match the stored cryptographic hash (Hash::check() === false).
  • The key's warehouse does not exist or does not belong to the associated company tenant.

Secret Rotation & Key Lifecycle

  1. Creating Keys:
    • Go to Settings → API Keys in your Tracepos dashboard.
    • Click Generate New API Key.
    • Choose the branch Warehouse, configure the Rate Limit, and select the required Scopes (read, write, inventory).
    • Copy the secret key immediately. It will not be shown again.
  2. Replacing Compromised or Lost Keys:
    • If a secret is lost or exposed, generate a replacement API key with the identical scopes.
    • Update your backend environment variables with the new key pair.
    • Immediately disable or delete the old API key in the Tracepos dashboard.
  3. Legacy Credential Invalidation:
    • When the security migration (php artisan migrate) is applied on your instance, existing legacy credentials with reversible hashes are invalidated. Replacement keys must be provisioned with explicit scopes.

Code Samples

cURL
curl -X GET "https://app.tracepos.net/api/v1/public/warehouses" \
  -H "X-Tracepos-Public-Key: Trp-pk-YOUR_PUBLIC_KEY" \
  -H "X-Tracepos-Secret-Key: Trp-sk-YOUR_SECRET_KEY" \
  -H "Accept: application/json"
Node.js (Axios)
const axios = require('axios');

const client = axios.create({
  baseURL: 'https://app.tracepos.net/api/v1/public',
  headers: {
    'X-Tracepos-Public-Key': process.env.TRACEPOS_PUBLIC_KEY,
    'X-Tracepos-Secret-Key': process.env.TRACEPOS_SECRET_KEY,
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

// Example authenticated call
client.get('/products')
  .then(res => console.log('Products:', res.data))
  .catch(err => {
    if (err.response?.status === 401) {
      console.error('Auth Error: Invalid API credentials.');
    } else if (err.response?.status === 403) {
      console.error('Forbidden: Key lacks required scope.');
    } else if (err.response?.status === 429) {
      console.error('Rate Limit: Throttled, retry in 60s.');
    }
  });
Python (Requests)
import os
import requests

HEADERS = {
    "X-Tracepos-Public-Key": os.environ["TRACEPOS_PUBLIC_KEY"],
    "X-Tracepos-Secret-Key": os.environ["TRACEPOS_SECRET_KEY"],
    "Accept": "application/json",
    "Content-Type": "application/json",
}

response = requests.get(
    "https://app.tracepos.net/api/v1/public/products",
    headers=HEADERS
)

if response.status_code == 401:
    print("Authentication failed: Invalid API credentials.")
elif response.status_code == 403:
    print("Scope error: API key missing required permission.")
elif response.status_code == 429:
    print("Rate limited: Too many requests.")
else:
    print(response.json())
PHP (Guzzle)
<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\ClientException;

$client = new Client([
    'base_uri' => 'https://app.tracepos.net/api/v1/public/',
    'headers' => [
        'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
        'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
        'Accept'                => 'application/json',
        'Content-Type'          => 'application/json',
    ]
]);

try {
    $response = $client->get('products');
    echo $response->getBody();
} catch (ClientException $e) {
    echo $e->getResponse()->getBody();
}
Prev
Getting Started
Next
Postman Collection