Authentication

MPPFi uses API keys and cryptographic agent identities to authenticate requests. All API requests must include a valid API key, and agent operations require cryptographic signatures.

---

Overview

MPPFi employs a dual authentication model:

1. API Keys: Authenticate your organization/developer account

2. Agent Identities: Cryptographic keypairs for individual AI agents

This separation ensures that:

• Developers control API access at the organizational level

• AI agents have individual cryptographic identities for autonomous operations

• Spending policies are enforced per-agent with blockchain-level security

---

API Key Authentication

Key Types

Production Keys

Used for live transactions with real money on Solana mainnet.

Format: mppfi_live_...

Use for:

• Production AI agent deployments

• Real USDC transactions

• Mainnet Solana settlements

Sandbox Keys

Used for testing without real money on Solana devnet.

Format: mppfi_test_...

Use for:

• Development and testing

• Devnet USDC (testnet tokens)

• Sandbox MPP merchants

---

Getting Your API Key

1. Sign up at mppfi.xyz/signup

2. Complete account verification (for production keys)

3. Navigate to Settings → API Keys

4. Click Generate New Key

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

6. Note the key prefix: mppfi_live_ or mppfi_test_

---

Using Your API Key

HTTP Requests

Include your API key in the Authorization header:

curl https://api.mppfi.xyz/v1/agents \
  -H "Authorization: Bearer mppfi_live_abc123..." \
  -H "Content-Type: application/json"

SDK Authentication

TypeScript/Node.js

import { MPPFi } from '@mppfi/sdk';

const mppfi = new MPPFi({
  apiKey: process.env.MPPFI_API_KEY,
  network: 'mainnet-beta'
});

// Sandbox environment
const sandbox = new MPPFi({
  apiKey: process.env.MPPFI_SANDBOX_KEY,
  network: 'devnet'
});

Python

import mppfi
import os

client = mppfi.Client(
    api_key=os.environ.get('MPPFI_API_KEY'),
    network='mainnet-beta'
)

# Sandbox environment
sandbox = mppfi.Client(
    api_key=os.environ.get('MPPFI_SANDBOX_KEY'),
    network='devnet'
)

Rust

use mppfi::MPPFi;

fn main() {
    let client = MPPFi::new(
        std::env::var("MPPFI_API_KEY").unwrap(),
        "mainnet-beta",
    );

    // Sandbox environment
    let sandbox = MPPFi::new(
        std::env::var("MPPFI_SANDBOX_KEY").unwrap(),
        "devnet",
    );
}

---

Agent Identity Authentication

Each AI agent has a cryptographic identity (public/private keypair) managed by MPPFi.

How Agent Identity Works

1. Account Creation: When you create an agent, MPPFi generates a keypair

2. Key Storage: Private keys stored in Hardware Security Modules (HSM)

3. Transaction Signing: Agent transactions signed with agent's private key

4. On-Chain Verification: Solana verifies signatures on-chain

Agent Authentication Flow

// 1. Create agent (MPPFi generates keypair)
const agent = await mppfi.agents.create({
  name: 'PaymentBot',
  initialFunding: { amount: 1000_00, currency: 'USDC' }
});

console.log('Agent ID:', agent.id);
console.log('Public Key:', agent.publicKey);
console.log('Solana Address:', agent.solanaAddress);
console.log('MPP Endpoint:', agent.mppEndpoint);

// 2. Agent makes payment (automatically signed with agent's private key)
const payment = await mppfi.payments.create({
  agentId: agent.id, // Identifies which agent
  merchantUrl: 'https://api.service.com/mpp',
  amount: 50_00
});

// MPPFi automatically:
// - Signs transaction with agent's private key
// - Validates against spending policy
// - Submits to Solana blockchain
// - Returns cryptographic proof

Hierarchical Key Management

For advanced use cases, you can manage agent keys hierarchically:

// Parent agent with sub-agents
const parentAgent = await mppfi.agents.create({
  name: 'OrchestrationBot',
  type: 'parent',
  initialFunding: { amount: 10000_00, currency: 'USDC' }
});

// Create child agent under parent
const childAgent = await mppfi.agents.createChild({
  parentId: parentAgent.id,
  name: 'WorkerBot-01',
  derivationPath: "m/44'/501'/0'/0'", // HD wallet path
  spendingLimit: { amount: 100_00, currency: 'USDC' }
});

console.log('Parent:', parentAgent.publicKey);
console.log('Child:', childAgent.publicKey);
console.log('Derived from parent using HD wallet standard');

---

Security Best Practices

Never Commit API Keys

Add API keys to .gitignore:

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

Use Environment Variables

Store keys in environment variables, not source code:

# .env
MPPFI_API_KEY=mppfi_live_abc123...
MPPFI_SANDBOX_KEY=mppfi_test_xyz789...

// Load from environment
const mppfi = new MPPFi({
  apiKey: process.env.MPPFI_API_KEY
});

Separate Keys for Each Environment

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

const getApiKey = () => {
  switch (process.env.NODE_ENV) {
    case 'production':
      return process.env.MPPFI_PRODUCTION_KEY;
    case 'staging':
      return process.env.MPPFI_STAGING_KEY;
    default:
      return process.env.MPPFI_SANDBOX_KEY;
  }
};

const mppfi = new MPPFi({
  apiKey: getApiKey(),
  network: process.env.NODE_ENV === 'production' ? 'mainnet-beta' : 'devnet'
});

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

// Rotate key programmatically
const newKey = await mppfi.apiKeys.create({
  name: 'Production Key - Q2 2026',
  permissions: ['agents:*', 'payments:*', 'policies:*'],
  expiresAt: '2026-06-30T23:59:59Z'
});

// Update environment and deploy
// Then revoke old key
await mppfi.apiKeys.revoke('key_old123');

Restrict Key Permissions

Create API keys with limited scopes:

// Read-only key for analytics
const readOnlyKey = await mppfi.apiKeys.create({
  name: 'Analytics Dashboard',
  permissions: [
    'agents:read',
    'transactions:read',
    'policies:read',
    'analytics:read'
  ]
});

// Agent-specific key
const agentKey = await mppfi.apiKeys.create({
  name: 'Agent Operations',
  permissions: [
    'agents:create',
    'agents:read',
    'payments:create',
    'transactions:read'
  ],
  limits: {
    dailySpending: 5000_00,
    monthlySpending: 100000_00
  }
});

---

Key Rotation

Manual Rotation

1. Generate New Key

   # Via dashboard or API
   curl https://api.mppfi.xyz/v1/api-keys \
     -H "Authorization: Bearer mppfi_live_current_key..." \
     -H "Content-Type: application/json" \
     -d '{"name":"Rotated Key 2026-03-30","permissions":["*"]}'

2. Update Application

   # Update environment variable
   export MPPFI_API_KEY=mppfi_live_new_key...
   
   # Restart application
   pm2 restart app

3. Test New Key

   # Verify new key works
   curl https://api.mppfi.xyz/v1/agents \
     -H "Authorization: Bearer mppfi_live_new_key..."

4. Revoke Old Key

   curl -X DELETE https://api.mppfi.xyz/v1/api-keys/key_old123 \
     -H "Authorization: Bearer mppfi_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: 'mppfi/api-key'
  });

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

const mppfi = new MPPFi({
  apiKey: await getApiKey(),
  network: 'mainnet-beta'
});

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/mppfi');
  return result.data.data.api_key;
}

const mppfi = new MPPFi({
  apiKey: await getApiKey(),
  network: 'mainnet-beta'
});

---

IP Whitelisting

Restrict API key usage to specific IP addresses or CIDR ranges:

// Configure IP whitelist via API
await mppfi.apiKeys.update('key_abc123', {
  ipWhitelist: [
    '203.0.113.10',      // Production server 1
    '203.0.113.11',      // Production server 2
    '198.51.100.0/24',   // Office network
    '2001:db8::/32'      // IPv6 range
  ]
});

// Requests from other IPs will be rejected

---

Rate Limiting

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

Plan	Requests/Minute	Requests/Hour	Burst
Sandbox	100	1,000	150
Starter	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: 1711800000
X-RateLimit-Policy: per-key

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 agent = await makeRequestWithRetry(() =>
  mppfi.agents.create({ name: 'Test Agent', initialFunding: { amount: 100_00, currency: 'USDC' } })
);

---

Webhook Signature Verification

Verify webhook authenticity using HMAC-SHA256 signatures:

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

const app = express();

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

    // Verify timestamp (prevent replay attacks)
    const now = Math.floor(Date.now() / 1000);
    if (Math.abs(now - parseInt(timestamp)) > 300) { // 5 minutes
      return res.status(401).send('Timestamp too old');
    }

    // Compute expected signature
    const expectedSignature = crypto
      .createHmac('sha256', secret)
      .update(`${timestamp}.${payload}`)
      .digest('hex');

    // Verify signature (timing-safe comparison)
    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 mppfi.apiKeys.getUsage('key_abc123', {
  period: '30d'
});

console.log('API Key Usage:');
console.log('  Total requests:', usage.totalRequests);
console.log('  Failed requests:', usage.failedRequests);
console.log('  Rate limited:', usage.rateLimitedRequests);
console.log('  Top endpoints:', usage.topEndpoints);
console.log('  Geographic distribution:', usage.geoDistribution);
console.log('  Last used:', usage.lastUsedAt);

// Monitor for suspicious activity
if (usage.failedAuthAttempts > 10) {
  console.warn('Unusual failed auth attempts detected');
  await mppfi.apiKeys.disable('key_abc123');
  await sendSecurityAlert({
    type: 'suspicious_activity',
    keyId: 'key_abc123',
    details: usage
  });
}

---

API Key Scopes

Available Scopes

Scope	Description
agents:create	Create new agent accounts
agents:read	View agent details and balances
agents:update	Update agent settings
agents:delete	Delete agent accounts
payments:create	Initiate payments
payments:read	View payment history
policies:create	Create spending policies
policies:read	View policies
policies:update	Modify policies
policies:delete	Delete policies
transactions:read	View transaction history
webhooks:*	Manage webhooks
analytics:read	Access analytics data
*	All permissions (admin)

Scope Examples

Read-Only Key

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

Agent Management Key

const agentKey = await mppfi.apiKeys.create({
  name: 'Agent Operations',
  scopes: [
    'agents:create',
    'agents:read',
    'agents:update',
    'payments:create',
    'transactions:read'
  ],
  limits: {
    dailySpending: 10000_00,
    monthlySpending: 200000_00
  }
});

Admin Key (Use Sparingly)

const adminKey = await mppfi.apiKeys.create({
  name: 'Platform Administrator',
  scopes: ['*'], // All permissions
  requiresMFA: true,
  expiresAt: '2026-06-30T23:59:59Z',
  ipWhitelist: ['203.0.113.10'] // Restrict to specific IP
});

---

Testing Authentication

Verify API Key

curl https://api.mppfi.xyz/v1/auth/verify \
  -H "Authorization: Bearer mppfi_live_abc123..."

Response:

{
  "valid": true,
  "keyId": "key_abc123",
  "scopes": ["*"],
  "expiresAt": null,
  "network": "mainnet-beta",
  "rateLimit": {
    "limit": 1000,
    "remaining": 999,
    "reset": 1711800000
  },
  "metadata": {
    "createdAt": "2026-01-15T10:00:00Z",
    "lastUsedAt": "2026-03-30T12:34:56Z"
  }
}

SDK Health Check

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

---

Troubleshooting

Invalid API Key

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

Insufficient Permissions

try {
  await mppfi.agents.delete('agent_123');
} catch (error) {
  if (error.code === 'insufficient_permissions') {
    console.error('API key lacks required scope:', error.requiredScope);
    console.error('Current scopes:', error.currentScopes);
    console.error('Update key permissions or use a different key');
  }
}

Key Expired

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

Network Mismatch

try {
  // Using mainnet key with devnet network
  const mppfi = new MPPFi({
    apiKey: 'mppfi_live_...', // Mainnet key
    network: 'devnet' // Devnet network - MISMATCH
  });
  await mppfi.agents.list();
} catch (error) {
  if (error.code === 'network_mismatch') {
    console.error('API key network does not match specified network');
    console.error('Key network:', error.keyNetwork);
    console.error('Specified network:', error.specifiedNetwork);
  }
}

---

Next Steps

• Quickstart Guide - Create your first agent

• Agent Accounts - Account management operations

• Spending Policies - Configure authorization rules

• API Reference - Complete authentication endpoints

---

Support

• Security Issues: [email protected]

• Documentation: docs.mppfi.xyz

• Discord: discord.gg/mppfi

• Status: status.mppfi.xyz