Skip to main content

​
Authentication

The ZenFlow API uses API Keys to authenticate requests. You can manage your API keys from the ZenFlow dashboard.

​
Getting an API Key

  1. Log in to your ZenFlow Dashboard
  2. Navigate to Settings > API Keys
  3. Click Create API Key
  4. Configure your key:
    • Name: A descriptive name (e.g., “ERP Integration”)
    • Scopes: Select the permissions your key needs
    • Expiration: Optional expiration date
  5. Click Create
  6. Copy your API key immediately - it won’t be shown again
Store your API key securely. Never commit it to version control or expose it in client-side code.

​
Using Your API Key

Include your API key in the X-API-Key header with every request: 
curl -X GET "https://api.zenflow.com.ar/api/v1/orders" \
  -H "X-API-Key: zenflow_live_abc123..."

​
API Key Format

ZenFlow API keys follow this format: 
zenflow_live_<random_string>
zenflow_test_<random_string>
  • zenflow_live_*: Production keys
  • zenflow_test_*: Test/sandbox keys (coming soon)

​
Scopes

API keys are scoped to specific permissions. Available scopes:
ScopeDescription
read:ordersRead order data
write:ordersCreate and update orders
read:productsRead product catalog
write:productsCreate and update products
read:stockRead inventory levels
write:stockUpdate inventory
read:webhooksView webhook configurations
write:webhooksManage webhooks
adminFull access to all resources

​
Scope Presets

For common use cases, we offer preset scope combinations:
PresetScopesUse Case
Read Onlyread:orders, read:products, read:stockReporting and analytics
ERP Syncread:orders, write:orders, read:products, read:stock, write:stockFull ERP integration
Stock Syncread:products, read:stock, write:stockInventory synchronization
Full AccessadminAdministrative access

​
Error Responses

​
Invalid API Key

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked"
  }
}

​
Missing API Key

{
  "success": false,
  "error": {
    "code": "missing_api_key",
    "message": "API key is required. Include it in the X-API-Key header"
  }
}

​
Insufficient Permissions

{
  "success": false,
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the required scope: write:orders"
  }
}

​
Expired API Key

{
  "success": false,
  "error": {
    "code": "expired_api_key",
    "message": "This API key has expired"
  }
}

​
Security Best Practices

Use Environment Variables

Store API keys in environment variables, not in code

Minimum Permissions

Only request the scopes you actually need

Rotate Regularly

Rotate your API keys periodically

Monitor Usage

Review API key usage logs for suspicious activity

​
Example: Environment Variables

# .env file (never commit this!)
ZENFLOW_API_KEY=zenflow_live_abc123...

// Node.js
const apiKey = process.env.ZENFLOW_API_KEY;

# Python
import os
api_key = os.environ.get('ZENFLOW_API_KEY')

​
Rotating API Keys

To rotate an API key:
  1. Create a new API key with the same scopes
  2. Update your application to use the new key
  3. Verify the new key is working
  4. Revoke the old key
You can have multiple active API keys. This allows for zero-downtime rotation.

​
IP Whitelisting (Optional)

For additional security, you can restrict API key usage to specific IP addresses:
  1. Go to Settings > API Keys
  2. Select your API key
  3. Add allowed IP addresses or CIDR ranges
  4. Save changes
{
  "ip_whitelist": ["192.168.1.100", "10.0.0.0/24"]
}

​
Rate Limits

See Rate Limits for details on API rate limiting.