Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication Overview

Waffo Pancake supports two authentication methods for API access:
MethodUse CaseDescription
API KeyServer-to-server callsPermanent authentication using RSA-SHA256 signatures
Store SlugPublic checkout flowsPublic 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.
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

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 within 5 minutes of server time

​
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 -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 Developers Page

Navigate to Dashboard → Merchant → Integration → 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

FeatureAPI KeyStore Slug
Server-side useYesNo
Client-side useNoYes
Requires X-EnvironmentNoYes
Issue Session TokenYesNo
Create Checkout SessionYesYes
Product ManagementYesNo
GraphQL QueriesYesYes (public data only)
ValidityPermanent (key-controlled)-

​
Authentication Errors

StatusErrorSolution
401Invalid signatureCheck signing algorithm, private key, and timestamp freshness (5 min window)
401Invalid or expired tokenRe-authenticate or use a valid API Key
403Insufficient permissionsCheck if the role has access to the endpoint
400Missing authenticationEnsure 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