Authentication

Secure your API requests with API Key authentication

Authentication Overview

Waffo Pancake supports two authentication methods for API access:

Method	Use Case	Description
API Key	Server-to-server calls	Permanent authentication using RSA-SHA256 signatures
Store Slug	Public checkout flows	Public access using X-Store-Slug and X-Environment headers

---

API Key Authentication

API Keys provide permanent server-to-server authentication using RSA-SHA256 signatures. The private key never leaves your server.

Request Headers

X-Merchant-Id: MER_2aUyqjCzEIiEcYMKj7TZtw
X-Timestamp: 1705312200
X-Signature: BASE64_ENCODED_SIGNATURE
Content-Type: application/json

API Key authentication does not require the X-Environment header. Each API Key is bound to either test or prod at creation time. The environment is determined by which key successfully verifies the signature.

Using the SDK (Recommended)

import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

// All requests are automatically signed
const { store } = await client.stores.create({ name: "My Store" });

Signing Algorithm (Manual Integration)

If you’re not using the SDK, you need to implement RSA-SHA256 request signing:

1. Build the canonical request:
   canonicalRequest = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + SHA256_BASE64(BODY)

2. Sign with RSA-SHA256:
   signature = RSA-SHA256(canonicalRequest, privateKey)

3. Base64 encode:
   X-Signature = Base64(signature)

Manual Signing Examples

Node.js

const crypto = require('crypto');

const MERCHANT_ID = 'MER_2aUyqjCzEIiEcYMKj7TZtw';
const PRIVATE_KEY = `-----BEGIN RSA PRIVATE KEY-----
...your private key...
-----END RSA PRIVATE KEY-----`;

async function callApiWithSignature(method, path, body) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const bodyStr = JSON.stringify(body);
  const bodyHash = crypto.createHash('sha256').update(bodyStr).digest('base64');

  // Build canonical request
  const canonicalRequest = `${method}\n${path}\n${timestamp}\n${bodyHash}`;

  // RSA-SHA256 sign
  const signature = crypto.sign('sha256', Buffer.from(canonicalRequest), PRIVATE_KEY).toString('base64');

  const response = await fetch(`https://api.waffo.ai${path}`, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-Merchant-Id': MERCHANT_ID,
      'X-Timestamp': timestamp,
      'X-Signature': signature
    },
    body: bodyStr
  });

  return response.json();
}

// Usage
const result = await callApiWithSignature('POST', '/v1/actions/store/create-store', {
  name: 'My Store'
});

Private Key Security

• Never expose the private key in client-side code
• Do not commit private keys to version control
• Store private keys in environment variables
• Rotate keys regularly, especially after team changes
• Timestamp must be at most 5 minutes older than server time and at most 1 minute ahead of server time

Keep your server clock NTP-synced

The accepted timestamp window is asymmetric: from 5 minutes behind server time to 1 minute ahead of it. A clock running fast is the tighter constraint — if your server clock is more than 1 minute ahead, every signed request is rejected with 401 Unauthorized even though the signature itself is correct.

---

Store Slug Authentication

For public-facing checkout flows, use Store Slug authentication. This allows visitors to create checkout sessions and query public store data without API Key credentials.

Request Headers

X-Store-Slug: my-awesome-store-k8x2m9ab
X-Environment: test | prod
Content-Type: application/json

Example

cURL

curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "X-Store-Slug: my-awesome-store-k8x2m9ab" \
  -H "X-Environment: test" \
  -H "Content-Type: application/json" \
  -d '{"productId": "PROD_4cWAslE1GKkGeaOMl9Vbmy", "productType": "onetime", "currency": "USD"}'

---

Creating API Keys

1. Go to API & Development Page

   Navigate to Dashboard → API & Development → API Keys

2. Create API Key

   Click “Create API Key” to generate a new RSA key pair. The public key is sent to the server automatically.

3. Name and Configure

   Give it a descriptive name (e.g., “Production Server”) and select the target environment (Test or Production).

4. Download Private Key

   Download your private key immediately. It will not be shown again.

Deleting an API key is immediate and irreversible. Any requests signed with the deleted key will fail with 401 Unauthorized.

---

Authentication Method Comparison

Feature	API Key	Store Slug
Server-side use	Yes	No
Client-side use	No	Yes
Requires X-Environment	No	Yes
Issue Session Token	Yes	No
Create Checkout Session	Yes	Yes
Product Management	Yes	No
GraphQL Queries	Yes	Yes (public data only)
Validity	Permanent (key-controlled)	-

---

Authentication Errors

Status	Error	Solution
401	Invalid signature	Check signing algorithm, private key, and timestamp freshness (accepted window: 5 min behind to 1 min ahead of server time)
401	Invalid or expired token	Re-authenticate or use a valid API Key
403	Insufficient permissions	Check if the role has access to the endpoint
400	Missing authentication	Ensure required headers are present

{
  "data": null,
  "errors": [
    {
      "message": "Invalid signature",
      "layer": "gateway"
    }
  ]
}

---

Security Best Practices

1. Never expose private keys in client-side code, version control, or public repositories
2. Use HTTPS for all API requests
3. Verify Webhook signatures to prevent forged requests
4. Separate test and production keys — create distinct keys for each environment
5. Rotate keys regularly, especially after team member changes
6. Monitor API usage in the Dashboard for unusual activity