Authentication

Clawallex uses API keys to authenticate requests. All API requests must include a valid API key in the Authorization header.

API Key Types

Production Keys

Used for live transactions with real money. Available after account verification.

Format: clw_live_...

Sandbox Keys

Used for testing without real money. All transactions are simulated.

Format: clw_test_...

Getting Your API Key

1. Sign up at clawallex.app

2. Complete account verification (production keys only)

3. Navigate to Settings > API Keys

4. Click "Generate New Key"

5. Store your key securely—it won't be shown again

Using Your API Key

HTTP Requests

Include your API key in the Authorization header:

curl https://api.clawallex.app/v1/accounts \
  -H "Authorization: Bearer clw_live_abc123..." \
  -H "Content-Type: application/json"

SDK Authentication

TypeScript/Node.js

import { Clawallex } from '@clawallex/sdk';

const clawallex = new Clawallex({
  apiKey: process.env.CLAWALLEX_API_KEY
});

// Sandbox environment
const sandbox = new Clawallex({
  apiKey: process.env.CLAWALLEX_SANDBOX_KEY,
  environment: 'sandbox'
});

Python

import clawallex
import os

client = clawallex.Client(
    api_key=os.environ.get('CLAWALLEX_API_KEY')
)

# Sandbox environment
sandbox = clawallex.Client(
    api_key=os.environ.get('CLAWALLEX_SANDBOX_KEY'),
    environment='sandbox'
)

Go

import "github.com/clawallex/clawallex-go"

client := clawallex.New(os.Getenv("CLAWALLEX_API_KEY"))

// Sandbox environment
sandbox := clawallex.New(
    os.Getenv("CLAWALLEX_SANDBOX_KEY"),
    clawallex.WithEnvironment("sandbox"),
)

Security Best Practices

Never Commit API Keys

Add API keys to .gitignore:

.env
.env.local
.env.production
config/secrets.yml

Use Environment Variables

Store keys in environment variables, not source code:

# .env
CLAWALLEX_API_KEY=clw_live_abc123...
CLAWALLEX_SANDBOX_KEY=clw_test_xyz789...

// Load from environment
const clawallex = new Clawallex({
  apiKey: process.env.CLAWALLEX_API_KEY
});

Separate Keys for Each Environment

Use different API keys for development, staging, and production:

const clawallex = new Clawallex({
  apiKey: process.env.NODE_ENV === 'production'
    ? process.env.CLAWALLEX_PRODUCTION_KEY
    : process.env.CLAWALLEX_SANDBOX_KEY
});

Rotate Keys Regularly

Rotate API keys every 90 days or immediately if compromised:

1. Generate new API key in dashboard

2. Update application configuration with new key

3. Test that new key works

4. Revoke old key

Restrict Key Permissions

When creating API keys, limit permissions to only what's needed:

// Create restricted key via API
const key = await clawallex.apiKeys.create({
  name: 'Agent 001 - Read Only',
  permissions: [
    'accounts:read',
    'transactions:read',
    'cards:read'
  ],
  expiresAt: '2026-12-31'
});

Key Rotation

Manual Rotation

1. Generate New Key

   # Via dashboard or API
   curl https://api.clawallex.app/v1/api-keys \
     -H "Authorization: Bearer clw_live_current_key..." \
     -d "name=Rotated Key $(date +%Y-%m-%d)"

2. Update Application

   # Update environment variable
   export CLAWALLEX_API_KEY=clw_live_new_key...
   
   # Restart application
   pm2 restart app

3. Test New Key

   # Verify new key works
   curl https://api.clawallex.app/v1/accounts \
     -H "Authorization: Bearer clw_live_new_key..."

4. Revoke Old Key

   curl -X DELETE https://api.clawallex.app/v1/api-keys/key_old123 \
     -H "Authorization: Bearer clw_live_new_key..."

Automated Rotation

Use secrets management services for automatic rotation:

AWS Secrets Manager

import { SecretsManager } from '@aws-sdk/client-secrets-manager';

const secretsManager = new SecretsManager({ region: 'us-east-1' });

async function getApiKey() {
  const secret = await secretsManager.getSecretValue({
    SecretId: 'clawallex/api-key'
  });

  return JSON.parse(secret.SecretString).CLAWALLEX_API_KEY;
}

const clawallex = new Clawallex({
  apiKey: await getApiKey()
});

HashiCorp Vault

import vault from 'node-vault';

const vaultClient = vault({
  endpoint: 'http://vault:8200',
  token: process.env.VAULT_TOKEN
});

async function getApiKey() {
  const result = await vaultClient.read('secret/data/clawallex');
  return result.data.data.api_key;
}

const clawallex = new Clawallex({
  apiKey: await getApiKey()
});

IP Whitelisting

Restrict API key usage to specific IP addresses:

// Configure IP whitelist via API
await clawallex.apiKeys.update('key_abc123', {
  ipWhitelist: [
    '203.0.113.10',    // Production server
    '203.0.113.11',    // Backup server
    '198.51.100.0/24'  // Office network
  ]
});

Rate Limiting

API keys are subject to rate limits based on your plan:

Plan	Requests/Minute	Requests/Hour	Burst
Sandbox	100	1,000	150
Startup	1,000	10,000	1,500
Growth	5,000	50,000	7,500
Enterprise	Custom	Custom	Custom

Rate limit headers included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1678886400

Handling Rate Limits

async function makeRequestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 'rate_limit_exceeded') {
        const resetTime = error.rateLimitReset;
        const waitTime = (resetTime - Date.now()) + 1000;

        console.log(`Rate limited. Waiting ${waitTime}ms...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

// Usage
const account = await makeRequestWithRetry(() =>
  clawallex.accounts.create({ name: 'Test Account', currency: 'USD' })
);

Webhook Signature Verification

Verify webhook authenticity using signature verification:

import crypto from 'crypto';
import express from 'express';

const app = express();

app.post('/webhooks/clawallex',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-clawallex-signature'];
    const payload = req.body.toString();
    const secret = process.env.CLAWALLEX_WEBHOOK_SECRET;

    const expectedSignature = crypto
      .createHmac('sha256', secret)
      .update(payload)
      .digest('hex');

    if (!crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )) {
      return res.status(401).send('Invalid signature');
    }

    const event = JSON.parse(payload);
    // Process verified event

    res.sendStatus(200);
  }
);

API Key Monitoring

Monitor API key usage and security events:

// Get API key usage statistics
const usage = await clawallex.apiKeys.getUsage('key_abc123', {
  period: '30d'
});

console.log('Total requests:', usage.totalRequests);
console.log('Failed requests:', usage.failedRequests);
console.log('Top endpoints:', usage.topEndpoints);
console.log('Geographic distribution:', usage.geoDistribution);

// Monitor for suspicious activity
if (usage.failedAuthAttempts > 10) {
  console.warn('Unusual failed auth attempts detected');
  await clawallex.apiKeys.disable('key_abc123');
  await sendSecurityAlert(usage);
}

API Key Scopes

Create keys with limited permissions for different use cases:

Read-Only Key

const readOnlyKey = await clawallex.apiKeys.create({
  name: 'Analytics Dashboard',
  scopes: [
    'accounts:read',
    'transactions:read',
    'cards:read',
    'analytics:read'
  ]
});

Agent-Specific Key

const agentKey = await clawallex.apiKeys.create({
  name: 'AI Agent - Infrastructure',
  scopes: [
    'accounts:read',
    'transactions:create',
    'transactions:read',
    'cards:create',
    'cards:read',
    'cards:update'
  ],
  limits: {
    dailySpending: 10000,
    monthlySpending: 200000
  },
  metadata: {
    agent_id: 'openclaw_001',
    department: 'Engineering'
  }
});

Admin Key

const adminKey = await clawallex.apiKeys.create({
  name: 'Platform Administrator',
  scopes: ['*'], // All permissions
  requiresMFA: true,
  expiresAt: '2026-06-30'
});

Testing Authentication

Verify API Key

curl https://api.clawallex.app/v1/auth/verify \
  -H "Authorization: Bearer clw_live_abc123..."

Response:

{
  "valid": true,
  "keyId": "key_abc123",
  "scopes": ["*"],
  "expiresAt": null,
  "rateLimit": {
    "limit": 1000,
    "remaining": 999,
    "reset": 1678886400
  }
}

SDK Health Check

// Verify SDK configuration
try {
  const health = await clawallex.auth.verify();
  console.log('Authentication valid:', health.valid);
  console.log('Key ID:', health.keyId);
  console.log('Scopes:', health.scopes);
} catch (error) {
  console.error('Authentication failed:', error.message);
}

Troubleshooting

Invalid API Key

try {
  await clawallex.accounts.list();
} catch (error) {
  if (error.code === 'invalid_api_key') {
    console.error('API key is invalid or revoked');
    console.error('Check key in dashboard: https://clawallex.app/settings/api-keys');
  }
}

Insufficient Permissions

try {
  await clawallex.accounts.delete('acc_123');
} catch (error) {
  if (error.code === 'insufficient_permissions') {
    console.error('API key lacks required scope:', error.requiredScope);
    console.error('Current scopes:', error.currentScopes);
  }
}

Key Expired

try {
  await clawallex.accounts.list();
} catch (error) {
  if (error.code === 'api_key_expired') {
    console.error('API key expired at:', error.expiredAt);
    console.error('Generate new key at: https://clawallex.app/settings/api-keys');
  }
}

Next Steps

• Quickstart Guide - Deploy your first treasury account

• Treasury Accounts - Account management operations

• Webhooks - Webhook signature verification

• API Reference - Complete authentication endpoints

Support

• Security Issues: [email protected]

• Documentation: docs.clawallex.app

• Discord: discord.gg/clawallex