Authorization Engine

Deep dive into ClawPay's programmable authorization logic.

Overview

The Authorization Engine is the core component that validates every transaction against user-defined rules. Unlike traditional banking where you give merchants unlimited access to your account, ClawPay uses AI agent permissions to enforce spending permissions.

Architecture

┌─────────────────┐
│   Transaction   │
│     Request     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Authorization  │
│     Engine      │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
┌───────┐ ┌───────────┐
│ Policy│ │ ZK Proof  │
│ Check │ │ Validator │
└───┬───┘ └─────┬─────┘
    │           │
    └─────┬─────┘
          │
          ▼
    ┌──────────┐
    │ Approve/ │
    │ Decline  │
    └──────────┘

How It Works

1. Transaction Initiation

When a card transaction occurs:

{
  cardId: 'card_123',
  amount: 49.99,
  currency: 'USD',
  merchant: {
    name: 'Amazon Web Services',
    category: 'cloud_services',
    mcc: '5734'
  },
  timestamp: '2024-01-15T14:22:33Z'
}

2. Policy Retrieval

The engine fetches authorization policies for the card's vault:

{
  type: 'whitelist_only',
  dailyLimit: 5000,
  merchants: ['aws.amazon.com', 'vercel.com'],
  categories: ['cloud_services'],
  zkProofRequired: true
}

3. Rule Evaluation

The engine evaluates multiple checks:

const checks = [
  checkDailyLimit(transaction, policy),
  checkMerchantWhitelist(transaction, policy),
  checkCategoryAllowed(transaction, policy),
  checkVaultBalance(transaction, vault),
  checkTimeRestrictions(transaction, policy),
  checkVelocityLimits(transaction, card)
];

const allPassed = checks.every(check => check.passed);

4. Zero-Knowledge Proof

If required, validate ZK-proof:

const proofValid = await validateZKProof(transaction, {
  prover: transaction.cardHolder,
  statement: 'transaction_authorized',
  publicInputs: [transaction.amount, transaction.merchant]
});

5. Decision

if (allPassed && proofValid) {
  return { approved: true };
} else {
  return {
    approved: false,
    reason: 'merchant_not_whitelisted'
  };
}

Authorization Policies

Policy Types

1. Whitelist Policy

Only allow pre-approved merchants:

{
  type: 'whitelist_only',
  dailyLimit: 5000,
  weeklyLimit: 30000,
  monthlyLimit: 100000,
  currency: 'USDC',
  merchants: [
    'amazon.com',
    'aws.amazon.com',
    'vercel.com'
  ],
  categories: [
    'cloud_services',
    'software'
  ]
}

Use case: Company treasury with strict vendor management.

2. Multi-Party Approval

Require multiple signatures for large transactions:

{
  type: 'multi_party',
  requiresApproval: {
    above: 10000,
    minApprovers: 2,
    approvers: [
      '[email protected]',
      '[email protected]',
      '[email protected]'
    ],
    timeoutMinutes: 60
  }
}

How it works:

Transaction over threshold is held pending
Approval request sent to designated approvers
Must receive minimum approvals within timeout
If approved, transaction proceeds
If timeout expires, transaction is declined

3. Velocity Control

Prevent rapid successive transactions:

{
  type: 'velocity_control',
  maxTransactionsPerHour: 10,
  maxTransactionsPerDay: 50,
  maxAmountPerHour: 5000,
  minTimeBetween: 60, // seconds
  requireCoolingPeriod: {
    after: 5, // transactions
    cooldown: 300 // seconds
  }
}

Use case: Fraud prevention and rate limiting.

4. Time-Based Restrictions

Limit transactions to specific times:

{
  type: 'time_restricted',
  allowedDays: ['monday', 'tuesday', 'wednesday', 'thursday', 'friday'],
  allowedHours: {
    start: '09:00',
    end: '17:00',
    timezone: 'America/New_York'
  },
  blockHolidays: true,
  holidays: ['2024-12-25', '2024-01-01']
}

Use case: Business hours only spending.

5. Geographic Restrictions

Control where cards can be used:

{
  type: 'geographic',
  allowedCountries: ['US', 'CA'],
  blockedCountries: ['XX', 'YY'],
  allowedRegions: ['US-CA', 'US-NY'],
  requireGeoMatch: true // Cardholder location must match
}

Combining Policies

Multiple policies can be applied simultaneously:

await client.vaults.setAuthorizationPolicy('vault_123', {
  // Base limits
  dailyLimit: 5000,
  monthlyLimit: 100000,

  // Merchant controls
  type: 'whitelist_only',
  merchants: ['aws.amazon.com', 'vercel.com'],

  // Multi-party for large amounts
  requiresApproval: {
    above: 10000,
    minApprovers: 2
  },

  // Time restrictions
  allowedHours: {
    start: '09:00',
    end: '17:00'
  },

  // Velocity controls
  maxTransactionsPerHour: 10,

  // Privacy
  zkProofRequired: true
});

The engine evaluates all rules. Transaction must pass every check.

Advanced Features

Dynamic Limits

Limits can adjust based on context:

{
  type: 'dynamic',
  baseDailyLimit: 1000,
  modifiers: [
    {
      condition: 'day_of_week',
      values: ['saturday', 'sunday'],
      multiplier: 0.5 // 50% of base limit on weekends
    },
    {
      condition: 'merchant_category',
      value: 'emergency_services',
      multiplier: 2.0 // Double limit for emergencies
    }
  ]
}

Contextual Authorization

Authorization can consider additional context:

{
  type: 'contextual',
  rules: [
    {
      if: {
        merchantCategory: 'travel',
        amount: { gt: 500 }
      },
      then: {
        requireApproval: true,
        require2FA: true
      }
    },
    {
      if: {
        cardholderLocation: { ne: 'US' }
      },
      then: {
        dailyLimit: 500 // Lower limit when traveling
      }
    }
  ]
}

Machine Learning Fraud Detection

The engine can incorporate ML-based risk scores:

{
  type: 'ml_enhanced',
  fraudThreshold: 0.75, // 0-1 risk score
  onHighRisk: 'require_approval',
  factors: [
    'transaction_amount',
    'merchant_reputation',
    'time_of_day',
    'location_anomaly',
    'velocity_pattern'
  ]
}

Zero-Knowledge Proofs

Why ZK-Proofs?

Zero-knowledge proofs allow transaction validation without revealing:

Transaction amounts
Merchant details
Cardholder identity
Vault balance

Only the fact that authorization is valid is proven.

Enabling ZK-Proofs

await client.vaults.setAuthorizationPolicy('vault_123', {
  zkProofRequired: true,
  zkProofType: 'groth16', // or 'plonk', 'stark'
  publicInputs: ['merchant_category', 'amount_range'],
  privateInputs: ['exact_amount', 'merchant_name']
});

How It Works

Prover (cardholder) generates proof:

const proof = generateProof({
  statement: 'I have authorization to spend at this merchant',
  witnesses: {
    vaultBalance: 10000,
    merchantWhitelist: ['aws.amazon.com'],
    amount: 49.99
  }
});

Verifier (authorization engine) checks proof:

const valid = verifyProof(proof, publicInputs);
// Returns true/false without learning private details

Transaction proceeds if proof is valid.

Performance

Proof System

Generation Time

Verification Time

Proof Size

Groth16

~2s

~5ms

128 bytes

PLONK

~5s

~10ms

512 bytes

STARK

~10s

~20ms

45 KB

Times are approximate and hardware-dependent

Approval Workflows

Manual Approval Flow

// 1. Transaction triggers approval requirement
const txn = await client.transactions.retrieve('txn_pending');
// status: 'pending_approval'

// 2. Approvers receive notification
// Email, SMS, or webhook sent to approvers

// 3. Approver reviews and approves
await client.transactions.approve('txn_pending', {
  approverId: 'user_cfo',
  comment: 'Approved for Q1 infrastructure',
  signature: 'crypto_signature_here'
});

// 4. Transaction proceeds after minimum approvals
// status changes to 'approved' -> 'completed'

Conditional Approval

await client.vaults.setAuthorizationPolicy('vault_123', {
  requiresApproval: {
    conditions: [
      {
        when: {
          amount: { gt: 10000 }
        },
        then: {
          minApprovers: 2,
          approvers: ['[email protected]', '[email protected]']
        }
      },
      {
        when: {
          merchantCategory: 'high_risk'
        },
        then: {
          minApprovers: 1,
          approvers: ['[email protected]'],
          require2FA: true
        }
      }
    ]
  }
});

Monitoring & Analytics

Authorization Metrics

const metrics = await client.vaults.getAuthorizationMetrics('vault_123', {
  period: '30d'
});

console.log(`Approval rate: ${metrics.approvalRate}%`);
console.log(`Decline rate: ${metrics.declineRate}%`);
console.log(`Pending approvals: ${metrics.pendingApprovals}`);
console.log(`Average approval time: ${metrics.avgApprovalTime}ms`);

Decline Analysis

const declines = await client.transactions.list({
  vaultId: 'vault_123',
  status: 'declined'
});

const reasonBreakdown = {};
declines.forEach(txn => {
  reasonBreakdown[txn.declineReason] =
    (reasonBreakdown[txn.declineReason] || 0) + 1;
});

console.log('Decline reasons:', reasonBreakdown);
// {
//   daily_limit_exceeded: 5,
//   merchant_not_whitelisted: 12,
//   insufficient_balance: 3
// }

Policy Effectiveness

const effectiveness = await client.vaults.analyzePolicyEffectiveness('vault_123', {
  period: '90d'
});

console.log('Policy effectiveness report:');
console.log(`- Fraud prevented: $${effectiveness.fraudPrevented}`);
console.log(`- Legitimate declines: ${effectiveness.falsePositives}`);
console.log(`- Policy violations: ${effectiveness.violations}`);
console.log(`Recommended adjustments:`, effectiveness.recommendations);

Best Practices

1. Start Restrictive, Relax Gradually

// Week 1: Very restrictive
await client.vaults.setAuthorizationPolicy(vaultId, {
  dailyLimit: 1000,
  merchants: ['known_vendor_1', 'known_vendor_2']
});

// After observing patterns, gradually relax
await client.vaults.setAuthorizationPolicy(vaultId, {
  dailyLimit: 5000,
  categories: ['cloud_services', 'software']
});

2. Use Webhooks for Real-Time Monitoring

app.post('/webhooks/clawpay', (req, res) => {
  const event = req.body;

  if (event.type === 'authorization.required') {
    notifyApprovers(event.data.object);
  }

  if (event.type === 'transaction.declined') {
    analyzeDeclinePattern(event.data.object);
  }

  res.sendStatus(200);
});

3. Regular Policy Reviews

// Monthly policy review
async function reviewPolicy(vaultId) {
  const metrics = await client.vaults.getAuthorizationMetrics(vaultId, {
    period: '30d'
  });

  if (metrics.declineRate > 20) {
    console.log('High decline rate - consider relaxing policy');
  }

  if (metrics.approvalRate < 90) {
    console.log('Many approvals needed - adjust thresholds');
  }
}

4. Test Policies in Sandbox

// Test in sandbox before applying to production
const sandboxClient = new ClawPay({
  apiKey: process.env.CLAWPAY_SANDBOX_KEY,
  environment: 'sandbox'
});

await sandboxClient.vaults.setAuthorizationPolicy(vaultId, newPolicy);

// Run test transactions
// Verify behavior
// Apply to production

Troubleshooting

Transaction Declined

Check which rule failed:

const txn = await client.transactions.retrieve('txn_declined');

console.log(`Decline reason: ${txn.declineReason}`);
console.log(`Failed check: ${txn.failedCheck}`);
console.log(`Policy ID: ${txn.policyId}`);

// View full evaluation details
const evaluation = await client.transactions.getAuthorizationEvaluation('txn_declined');
console.log('Rule evaluations:', evaluation.checks);

Approval Timeout

const txn = await client.transactions.retrieve('txn_timeout');

if (txn.status === 'declined' && txn.declineReason === 'approval_timeout') {
  console.log(`Timed out after ${txn.approvalTimeoutMinutes} minutes`);
  console.log(`Approvals received: ${txn.approvalsReceived}/${txn.approvalsRequired}`);

  // Manually retry if needed
  await client.transactions.retryApproval(txn.id, {
    extendTimeout: 30 // minutes
  });
}

Next Steps

PreviousSDK Documentation

Last updated 1 hour ago

Good evening

hashtagOverview

hashtagArchitecture

hashtagHow It Works

hashtag1. Transaction Initiation

hashtag2. Policy Retrieval

hashtag3. Rule Evaluation

hashtag4. Zero-Knowledge Proof

hashtag5. Decision

hashtagAuthorization Policies

hashtagPolicy Types

hashtag1. Whitelist Policy

hashtag2. Multi-Party Approval

hashtag3. Velocity Control

hashtag4. Time-Based Restrictions

hashtag5. Geographic Restrictions

hashtagCombining Policies

hashtagAdvanced Features

hashtagDynamic Limits

hashtagContextual Authorization

hashtagMachine Learning Fraud Detection

hashtagZero-Knowledge Proofs

hashtagWhy ZK-Proofs?

hashtagEnabling ZK-Proofs

hashtagHow It Works

hashtagPerformance

hashtagApproval Workflows

hashtagManual Approval Flow

hashtagConditional Approval

hashtagMonitoring & Analytics

hashtagAuthorization Metrics

hashtagDecline Analysis

hashtagPolicy Effectiveness

hashtagBest Practices

hashtag1. Start Restrictive, Relax Gradually

hashtag2. Use Webhooks for Real-Time Monitoring

hashtag3. Regular Policy Reviews

hashtag4. Test Policies in Sandbox

hashtagTroubleshooting

hashtagTransaction Declined

hashtagApproval Timeout

hashtagNext Steps

Overview

Architecture

How It Works

1. Transaction Initiation

2. Policy Retrieval

3. Rule Evaluation

4. Zero-Knowledge Proof

5. Decision

Authorization Policies

Policy Types

1. Whitelist Policy

2. Multi-Party Approval

3. Velocity Control

4. Time-Based Restrictions

5. Geographic Restrictions

Combining Policies

Advanced Features

Dynamic Limits

Contextual Authorization

Machine Learning Fraud Detection

Zero-Knowledge Proofs

Why ZK-Proofs?

Enabling ZK-Proofs

How It Works

Performance

Approval Workflows

Manual Approval Flow

Conditional Approval

Monitoring & Analytics

Authorization Metrics

Decline Analysis

Policy Effectiveness

Best Practices

1. Start Restrictive, Relax Gradually

2. Use Webhooks for Real-Time Monitoring

3. Regular Policy Reviews

4. Test Policies in Sandbox

Troubleshooting

Transaction Declined

Approval Timeout

Next Steps