> ## Documentation Index
> Fetch the complete documentation index at: https://docs.txncheck.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Overview

> Security best practices for TxnCheck API integration

# Security Overview

This guide covers security best practices for integrating with the TxnCheck API, protecting your API keys, and handling sensitive data.

## Security Architecture

```mermaid theme={null}
flowchart TD
    subgraph YourInfra [Your Infrastructure]
        A[Application Server]
        B[Secrets Manager]
        C[Audit Logs]
    end
    
    subgraph Transport [Secure Transport]
        D[TLS 1.3]
    end
    
    subgraph TxnCheck [TxnCheck]
        E[API Gateway]
        F[Rate Limiting]
        G[Request Validation]
    end
    
    B -->|API Key| A
    A -->|HTTPS| D
    D -->|Encrypted| E
    E --> F
    F --> G
    A -->|Log| C
```

## Key Security Principles

<CardGroup cols={2}>
  <Card title="Defense in Depth" icon="shield-halved">
    Multiple layers of security controls to protect against various attack vectors
  </Card>

  <Card title="Least Privilege" icon="lock">
    Grant minimum necessary permissions for API keys and service accounts
  </Card>

  <Card title="Zero Trust" icon="fingerprint">
    Verify every request, even from internal systems
  </Card>

  <Card title="Audit Everything" icon="file-lines">
    Log all API interactions for compliance and incident response
  </Card>
</CardGroup>

## Authentication Security

### API Key Protection

<Warning>
  Your API key grants access to paid services and sensitive verification data. Treat it like a password.
</Warning>

**Do:**

* Store API keys in a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.)
* Use environment variables, never hardcode keys
* Rotate keys periodically (every 90 days recommended)
* Use separate keys for development, staging, and production

**Don't:**

* Commit API keys to version control
* Share keys via email or chat
* Log API keys in application logs
* Expose keys in client-side code

```typescript theme={null}
// ✅ Good: Load from environment
const client = new TxnCheckClient({
  apiKey: process.env.FRAUD_BUSTER_API_KEY!,
});

// ❌ Bad: Hardcoded key
const client = new TxnCheckClient({
  apiKey: 'fb_live_abc123xyz',
});
```

### Request Signing (Optional but Recommended)

Enable HMAC-SHA256 request signing for additional security:

```typescript theme={null}
const client = new TxnCheckClient({
  apiKey: process.env.FRAUD_BUSTER_API_KEY!,
  secretKey: process.env.FRAUD_BUSTER_SECRET_KEY!, // For signing
});
```

Request signing provides:

* **Integrity**: Ensures request wasn't modified in transit
* **Replay Protection**: Timestamp prevents replay attacks
* **Non-repudiation**: Proves request originated from your system

## Transport Security

### HTTPS Requirements

All API communication must use HTTPS with TLS 1.2 or higher:

```typescript theme={null}
// The SDK enforces HTTPS by default
const client = new TxnCheckClient({
  apiKey: process.env.FRAUD_BUSTER_API_KEY!,
  baseUrl: 'https://api.txncheck.in/api/v1', // HTTPS required
});
```

### Certificate Validation

Always validate SSL certificates:

```typescript theme={null}
// ✅ Good: Default behavior - validates certificates
const response = await fetch(url);

// ❌ Bad: Disabling certificate validation
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'; // Never do this!
```

## Input Validation

Always validate input before sending to the API:

```typescript theme={null}
// Validate mobile number format
function validateMobile(mobile: string): boolean {
  return /^\+91\d{10}$/.test(mobile);
}

// Validate VPA format
function validateVPA(vpa: string): boolean {
  return /^[a-zA-Z0-9._-]+@[a-zA-Z0-9]+$/.test(vpa);
}

// Use validation before API calls
if (!validateMobile(userInput.mobile)) {
  throw new ValidationError('Invalid mobile number format');
}

const result = await client.upiByMobile(userInput.mobile, { sync: true });
```

## Rate Limiting

Implement client-side rate limiting to avoid hitting API limits:

```typescript theme={null}
import Bottleneck from 'bottleneck';

const limiter = new Bottleneck({
  reservoir: 100, // Initial tokens
  reservoirRefreshAmount: 100, // Refill amount
  reservoirRefreshInterval: 60 * 1000, // Refill every minute
  maxConcurrent: 5, // Max concurrent requests
});

async function rateLimitedRequest(mobile: string) {
  return limiter.schedule(() => client.upiByMobile(mobile, { sync: true }));
}
```

## Webhook Security

### Signature Verification

Always verify webhook signatures to ensure authenticity:

```typescript theme={null}
import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  timestamp: string,
  secretKey: string
): boolean {
  // Check timestamp to prevent replay attacks
  const webhookTime = parseInt(timestamp, 10);
  const currentTime = Date.now();
  const maxAge = 5 * 60 * 1000; // 5 minutes
  
  if (Math.abs(currentTime - webhookTime) > maxAge) {
    return false;
  }

  // Verify signature
  const message = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secretKey)
    .update(message)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
```

### Webhook Endpoint Security

Secure your webhook endpoint:

```typescript theme={null}
app.post('/webhook/fraud-buster', 
  // Rate limit webhooks
  rateLimit({ windowMs: 60000, max: 100 }),
  
  // Verify signature middleware
  webhookSignatureMiddleware(process.env.WEBHOOK_SECRET!),
  
  // Process webhook
  async (req, res) => {
    // Handle webhook...
    res.json({ status: 'ok' });
  }
);
```

## Error Handling Security

### Don't Expose Internal Errors

```typescript theme={null}
// ✅ Good: Generic error message to client
app.use((err, req, res, next) => {
  console.error('Internal error:', err); // Log full error
  res.status(500).json({
    error: 'An error occurred processing your request',
  });
});

// ❌ Bad: Exposing internal details
app.use((err, req, res, next) => {
  res.status(500).json({
    error: err.message,
    stack: err.stack, // Never expose stack traces!
  });
});
```

### Secure Logging

Log enough for debugging without exposing sensitive data:

```typescript theme={null}
// ✅ Good: Mask sensitive data in logs
function logAPICall(mobile: string, result: any) {
  console.log({
    action: 'verification',
    mobile: maskMobile(mobile), // +91****543210
    status: result.status,
    requestId: result.requestId,
    timestamp: new Date().toISOString(),
  });
}

function maskMobile(mobile: string): string {
  return mobile.slice(0, 3) + '****' + mobile.slice(-6);
}

// ❌ Bad: Logging full mobile numbers
console.log(`Verified mobile: ${mobile}`);
```

## Security Checklist

Before going to production, verify:

<AccordionGroup>
  <Accordion title="API Key Security">
    * [ ] API keys stored in secrets manager
    * [ ] No keys in source code or version control
    * [ ] Separate keys for dev/staging/production
    * [ ] Key rotation process documented
  </Accordion>

  <Accordion title="Transport Security">
    * [ ] All API calls use HTTPS
    * [ ] Certificate validation enabled
    * [ ] No sensitive data in URLs (use POST body)
  </Accordion>

  <Accordion title="Input Validation">
    * [ ] Mobile numbers validated before API calls
    * [ ] VPA formats validated
    * [ ] Input sanitization in place
  </Accordion>

  <Accordion title="Webhook Security">
    * [ ] Signature verification implemented
    * [ ] Timestamp validation (replay protection)
    * [ ] Rate limiting on webhook endpoint
    * [ ] HTTPS-only webhook URL
  </Accordion>

  <Accordion title="Logging & Monitoring">
    * [ ] Sensitive data masked in logs
    * [ ] API errors logged for debugging
    * [ ] Alerting on unusual patterns
    * [ ] Audit trail for compliance
  </Accordion>
</AccordionGroup>

## Incident Response

If you suspect your API key has been compromised:

1. **Immediately** rotate the API key in your dashboard
2. Review recent API usage for unauthorized calls
3. Check your systems for the source of the leak
4. Update all deployed applications with new keys
5. Contact TxnCheck support if needed

## Related Guides

<CardGroup cols={2}>
  <Card title="API Keys" icon="key" href="/security/api-keys">
    Detailed guide on managing API keys
  </Card>

  <Card title="Data Handling" icon="database" href="/security/data-handling">
    Handling PII and sensitive data
  </Card>

  <Card title="Compliance" icon="shield-check" href="/security/compliance">
    Regulatory compliance guidance
  </Card>

  <Card title="Authentication" icon="lock" href="/authentication">
    API authentication details
  </Card>
</CardGroup>