API Key Management

Create and manage scoped API keys for secure programmatic access to your merchant account. Each key can have specific permissions and optional IP restrictions.

Creating API Keys

API keys are created in the merchant portal under Settings → API Keys. When creating a key, you'll need to:

Name your key - Use a descriptive name for audit trail (e.g., "OpenClaw Integration", "Website Checkout")
Select scopes - Choose which permissions the key should have
Set expiration (optional) - Keys can have an optional expiry date
IP restrictions (optional) - Limit key usage to specific IP addresses

Example: Creating an OpenClaw Integration Key

For an OpenClaw skill that needs to send invoices and view sales history:

Name: OpenClaw Invoice Bot
Scopes: customer:read, customer:write, invoice:read, invoice:write, sales:read
Expiration: None (or 1 year for security)
IP Restrictions: None (or restrict to OpenClaw server IPs)

Key Security

API keys are stored securely using industry-standard practices:

Hashing

Keys are hashed using scrypt with a pepper before storage. The original key is only shown once during creation.

v1$salt$hash

Prefix Lookup

Keys are indexed by their first 16 characters for efficient lookup while maintaining security.

sntr_abcdefghijklmn

Managing Keys

You can view, revoke, and monitor all your API keys from the merchant portal:

Action	Description	Effect
Revoke Key	Immediately invalidates the key	Immediate
View Usage	See last used timestamp and request count	Read-only
Regenerate	Create new key, automatically revokes old	Key rotation

Audit Trail

All API key usage is logged with the key name for audit purposes:

{
  "timestamp": "2026-02-26T15:30:00Z",
  "apiKeyId": "cmm3znnc000026oqzs8nq58jm",
  "apiKeyName": "OpenClaw Invoice Bot",
  "merchantId": "cmm3zkkx000006ogg8arp52qb",
  "endpoint": "/public/api/v1/invoices",
  "method": "POST",
  "status": 201,
  "ip": "192.168.1.100"
}

Best Practices

✅ Principle of Least Privilege

Only grant the minimum scopes needed. If an integration only needs to read invoices, don't give it write permissions.

⚠️ Regular Rotation

Set expiration dates on keys and rotate them periodically (every 90-180 days for production keys).

🔒 IP Restrictions

For server-side integrations, restrict keys to specific IP addresses or CIDR ranges where your application runs.

📝 Descriptive Names

Use clear names that indicate the key's purpose. This helps with auditing and incident response.

Integration Examples

Here are common integration patterns with recommended scopes:

Integration Type	Recommended Scopes	Use Case
OpenClaw Skill	`customer:write,invoice:write,sales:read`	AI agent sending invoices
Website Checkout	`customer:write,invoice:write`	E-commerce payment processing
Analytics Dashboard	`sales:read,invoice:read`	Revenue reporting and analytics
CRM Integration	`customer:read,customer:write,invoice:read`	Customer data synchronization

Ready to Create Keys?

Access the API key management interface in your merchant portal to create your first scoped API key.

Go to API Key Settings View Customer API Docs →