Authentication

Learn how to authenticate your API requests with ShambaRecords

API Key Types

ShambaRecords provides two types of API keys to balance security and ease of use:

Public Key

sr_pub_1234567890abcdef

✓ Safe for client-side applications
✓ Read-only access to public data
✓ No signature required
✓ Easier to implement

Secret Key

sr_sec_1234567890abcdef

✓ Full API access
✓ HMAC signature required
✓ Server-side only (keep secure!)
✓ Advanced features and analytics

Security Warning

Never expose your secret key in client-side code, public repositories, or browser applications. Secret keys should only be used in secure server environments.

Public Key Authentication

Public key authentication is the simplest method. Just include your public key in theX-API-Key header:

Public Key Examplejavascript

// Public key authentication (simple)
const response = await fetch('https://api.shambarecords.com/api/v1/prices/latest', {
  headers: {
    'X-API-Key': 'sr_pub_your_public_key_here'
  }
});

const data = await response.json();

Available with Public Keys

• GET /api/v1/prices/latest - Latest price data
• GET /api/v1/products - List products
• GET /api/v1/markets - List markets
• GET /api/v1/counties - List counties
• GET /api/v1/crops - List crops

Secret Key Authentication

Secret key authentication uses HMAC-SHA256 signatures to verify request integrity and authenticity. This is required for write operations and advanced queries.

Required Headers

Header	Description
X-API-Key	Your secret API key (sr_sec_...)
X-Signature	HMAC-SHA256 signature of the request
X-Signature-Timestamp	Unix timestamp when signature was generated

Signature Computation

The signature is computed using HMAC-SHA256 with the following string:

Signature String Formattext

METHOD|PATH|TIMESTAMP|BODY

Components:

METHOD - HTTP method in uppercase (GET, POST, etc.)
PATH - Request path including query parameters
TIMESTAMP - Unix timestamp as string
BODY - Raw request body (empty string for GET requests)

Code Examples

import crypto from 'crypto';

// Your secret key (keep this secure!)
const SECRET_KEY = 'sr_sec_your_secret_key_here';

// Request payload
const requestBody = JSON.stringify({
  product_uuid: '550e8400-e29b-41d4-a716-446655440000',
  start_date: '2024-01-01',
  end_date: '2024-01-31'
});

// Generate timestamp (current Unix timestamp)
const timestamp = Math.floor(Date.now() / 1000).toString();

// Create signature string: METHOD|PATH|TIMESTAMP|BODY
const method = 'POST';
const path = '/api/v1/prices/search';
const signatureString = `${method}|${path}|${timestamp}|${requestBody}`;

// Generate HMAC-SHA256 signature
const signature = crypto
  .createHmac('sha256', SECRET_KEY)
  .update(signatureString)
  .digest('hex');

// Make request with authentication headers
const response = await fetch('https://api.shambarecords.com/api/v1/prices/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': SECRET_KEY,
    'X-Signature': signature,
    'X-Signature-Timestamp': timestamp
  },
  body: requestBody
});

const data = await response.json();
console.log(data);

Timestamp Validation

To prevent replay attacks, the API validates that the signature timestamp is within 5 minutes of the server time. If the timestamp is too old or too far in the future, the request will be rejected with a 401 error.

Best Practice

Always generate the timestamp immediately before making the request to ensure it falls within the valid time window.

Authentication Errors

When authentication fails, the API returns a 401 Unauthorized response with details about the error:

Error Responsejson

{
  "error": "unauthorized",
  "message": "Invalid signature",
  "code": "INVALID_SIGNATURE"
}

Common Error Codes

Code	Description
MISSING_API_KEY	X-API-Key header is missing
INVALID_API_KEY	API key is invalid or revoked
INVALID_SIGNATURE	Signature does not match expected value
TIMESTAMP_EXPIRED	Timestamp is outside valid window (±5 minutes)
INSUFFICIENT_PERMISSIONS	API key does not have required permissions