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

# Security Best Practices

> Essential security guidance for API integrations. Learn how to safely handle API tokens, protect sensitive data, and avoid common security pitfalls.

## Why Security Matters

When integrating with payment APIs, security isn't optional—it's critical. A compromised API token can give attackers full access to your account, allowing them to process payments, access customer data, and cause significant financial damage.

This guide covers essential security practices for server-to-server integrations with Revolv3. Follow these recommendations to keep your integration secure.

## Critical Rule: Never Expose Your Token

**`Never expose your x-revolv3-token (or any API key) in:`**

* Browser/client-side JavaScript
* Mobile app code (can be extracted from app bundles)
* URLs or query parameters (can be logged, cached, or leaked via referer headers)
* Logs, error messages, or debugging output
* Public repositories or version control
* Third-party analytics or monitoring tools

**Why this matters:**

* Client-side code can be inspected by anyone
* Tokens in URLs get logged by servers, proxies, and browsers
* Exposed tokens let attackers act as your server with full account access
* Once exposed, tokens can be used until you rotate them

## The Correct Pattern: Server-Side Integration

Always make API calls from your backend server, never from the browser or mobile app directly.

**How it works:**

1. **Store secrets server-side**: Keep your API token in environment variables or a secrets manager
2. **Make API calls from your backend**: Your server makes requests to Revolv3
3. **Return only needed data**: Send back to clients only the information they need (never the token)

**Example flow:**

```
Browser → Your Backend (with token) → Revolv3 API → Your Backend → Browser
```

The token never leaves your server.

## Secure Token Storage

### Use a Secrets Manager

Store your API tokens in a managed secrets store:

* **AWS**: Secrets Manager or Parameter Store
* **Azure**: Key Vault
* **Google Cloud**: Secret Manager
* **HashiCorp**: Vault
* **Other**: Any secure secrets management solution

### Environment Variables (Development Only)

For local development, you can use environment variables, but:

* Use them only for development
* Never commit `.env` files to version control
* Add `.env` to `.gitignore`
* Use a secrets manager for production

### What NOT to Do

* Hardcode tokens in source code
* Store tokens in configuration files that get committed
* Put tokens in database fields that aren't encrypted
* Share tokens via email, Slack, or other unsecured channels

## Secure Transport

### Always Use HTTPS

* **Always use HTTPS** (TLS 1.2 or higher) for all API requests
* **Enforce HSTS** (HTTP Strict Transport Security) on your servers
* **Never use HTTP** for any requests containing tokens or sensitive data

### Secure Headers

* Use the `x-revolv3-token` header (never put tokens in URLs)
* Require strong CORS policies if you have proxy endpoints
* Validate and sanitize all input before sending to Revolv3

## Logging and Monitoring

### What to Log

**Safe to log:**

* Request timestamps
* Endpoint names
* Response status codes
* Invoice IDs, customer IDs (non-sensitive identifiers)
* Last 4 characters of tokens (for identification): `tok_****1234`

**Never log:**

* Full API tokens
* Credit card numbers
* CVV codes
* Bank account numbers
* Full customer PII (personally identifiable information)

### Masking Sensitive Data

When you must log sensitive information for debugging:

* Show only the last 4 characters: `****1234`
* Hash tokens: `sha256(token)`
* Redact PII: `John D***` instead of `John Doe`

### Monitoring and Alerts

Set up monitoring for:

* **Unusual activity**: Requests from unexpected IP addresses
* **High volume**: Sudden spikes in API calls
* **Failed authentications**: Multiple 401 errors
* **Key rotation events**: When tokens are created, rotated, or revoked

Alert on suspicious patterns and enforce rate limits per token.

## Webhook Security

If you're receiving webhooks from Revolv3:

### Validate Webhook Signatures

* Always validate webhook signatures using the shared webhook secret
* Reject events that fail signature verification
* Check timestamp tolerance (reject events that are too old)

### Prevent Replay Attacks

* Use idempotency keys to deduplicate events
* Track event IDs to prevent processing the same event twice
* Implement timestamp validation (reject events outside a reasonable time window)

## Key Rotation

### When to Rotate

Rotate your API tokens:

* **Periodically**: Every 90-180 days as a best practice
* **After exposure**: Immediately if you suspect a token was compromised
* **After employee changes**: When someone with token access leaves
* **After security incidents**: Following any security breach

### How to Rotate Safely

1. **Create a new token** in the Revolv3 portal
2. **Update your secrets manager** with the new token
3. **Deploy to staging/sandbox** and test thoroughly
4. **Deploy to production** during low-traffic periods
5. **Monitor for errors** after deployment
6. **Revoke the old token** once you've confirmed the new one works

> **Tip**: Keep the old token active for 24-48 hours after rotation in case you need to roll back.

## Troubleshooting Security Issues

### If Your Token is Compromised

1. **Rotate immediately**: Create a new token and revoke the old one
2. **Search logs**: Check for unauthorized usage of the compromised token
3. **Review access**: Check what operations were performed with the token
4. **Notify stakeholders**: Inform your team and Revolv3 support
5. **Rotate downstream tokens**: If you have other tokens that might be affected, rotate those too

### If Webhooks Fail Signature Verification

1. **Check clock drift**: Ensure your server's clock is synchronized (use NTP)
2. **Verify shared secret**: Confirm you're using the correct webhook secret
3. **Check header parsing**: Ensure you're reading the signature header correctly
4. **Review timestamp tolerance**: Make sure your time window isn't too strict

## Compliance Considerations

* **PCI DSS**: If you handle card data, ensure you're PCI compliant
* **GDPR**: If processing EU customer data, follow GDPR requirements
* **Data retention**: Keep audit logs per your compliance needs
* **PII handling**: Redact or encrypt PII in logs per your privacy requirements

## Summary: Quick Security Checklist

* Never expose tokens in client-side code
* Store tokens in a secrets manager (not in code)
* Always use HTTPS for API requests
* Make API calls from your backend server only
* Rotate tokens periodically and after exposure
* Log only non-sensitive metadata
* Validate webhook signatures
* Monitor for unusual activity
* Use separate tokens for sandbox and production

## Next Steps

* [**Merchant Access Token**](/docs/authentication-security/merchant-access-token) — Learn how to get and use your API token
* [**Authentication**](/docs/authentication-security/merchant-access-token) — See token setup, required headers, and authentication troubleshooting
* [**Token FAQ**](/docs/authentication-security/token-faq) — Answers to common questions about tokens

***