--- title: "Best Practices" description: "Best practices for Autheona email validation API. Learn account management, access token security, API integration patterns, rule configuration, performance optimization, error handling, and production deployment strategies." keywords: "email validation best practices, api security best practices, access token management, rule configuration, api integration patterns, performance optimization, error handling, production deployment, email validation security" robots: index, follow permalink: /docs/guides/best-practices/ order: 3 category: Guides layout: docs.html --- # Best Practices Comprehensive recommendations for using Autheona effectively across all aspects of the platform - from account setup to API integration. ## Account Management ### Account Structure **One Account Per Product (Recommended for Most)** Use a single account for your product with multiple projects for different environments. Benefits: - Shared API quota across all environments - Single billing relationship - Easier management - Lower cost for small teams When to use: - Solo founders - Small teams - Products with moderate traffic - Multiple small projects **Separate Accounts Per Product** Use dedicated accounts when you need complete separation. When to use: - Large applications with high volume - Need dedicated quota per product - Separate billing required - Different teams managing products ### Account Security **Email and Password** - Use a strong, unique password - Store password in a password manager - Enable two-factor authentication when available - Don't share account credentials with team members (team features coming soon) **Email Address** - Use a company email, not personal - Use an alias that can be transferred (like `engineering@company.com`) - Avoid individual names in critical accounts - Keep email address current **Recovery** - Save magic sign-in links in a secure location - Document account recovery process for your team - Keep backup access methods updated ## Project Management ### Project Organization **Production vs Sandbox** Always maintain both: - Production project for live traffic - Sandbox project for testing and development Benefits: - Test rule changes safely - No quota impact from testing - Separate analytics - No risk to production **Naming Conventions** Use clear, descriptive names: - `ProductName - Production` - `ProductName - Staging` - `ProductName - Development` - `ProductName - Testing` Avoid: - Generic names like "Project 1" - Ambiguous names - Names without environment indicators **Project Descriptions** Always add descriptions: - Environment (production/staging/dev) - Purpose or use case - Owner or team - Last major configuration change ### Project Configuration **Start with Presets** Choose the preset closest to your use case: - Verified Sign Up - Unverified Sign Up - Magic Link - Newsletter Then customize from there. **Test Before Production** 1. Configure rules in sandbox project 2. Test with sample emails 3. Monitor validation results 4. Adjust rules based on results 5. Apply to production when validated **Document Changes** Keep a log of rule changes: - What was changed - Why it was changed - Expected impact - Actual results ### Project Deletion **Before Deleting** - Export any needed analytics data - Document why project is being deleted - Verify it's not in use - Confirm you have 30-day recovery window **After Deletion** - Remove project tokens from all systems - Update documentation - Notify team members - Set calendar reminder for permanent deletion date ## Access Token Management ### Token Creation **Naming Strategy** Use descriptive descriptions: - `Production Server - Never Expires` - `Staging Environment - 90 Days` - `Development - John's Local - 30 Days` Include: - Environment - Purpose - Owner (if personal) - Expiration strategy **Expiration Strategy** - **Never Expire**: Production servers only - **365 Days**: Long-term staging environments - **90 Days**: Standard development - **30 Days**: Personal development, testing **Multiple Tokens** Create separate tokens for: - Each environment (production, staging, dev) - Each developer (if needed) - Different services (web, mobile, background jobs) - Third-party integrations Benefits: - Granular revocation - Better tracking - Reduced blast radius if compromised ### Token Security **Storage** Never: - Commit to version control - Store in frontend code - Share via email or chat - Store in plain text files Always: - Use environment variables - Use secrets management (AWS Secrets Manager, HashiCorp Vault) - Encrypt at rest - Restrict access **Rotation** - Rotate tokens every 6-12 months - Rotate immediately if compromised - Rotate when team members leave - Rotate after security incidents **Rotation Process** 1. Create new token 2. Deploy new token to secondary systems 3. Verify new token works 4. Deploy to primary systems 5. Monitor for errors 6. Revoke old token after validation period ### Token Revocation **When to Revoke** - Compromised or suspected compromise - No longer needed - Team member leaves - Project deprecated - After rotation completion **Revocation Checklist** 1. Confirm token is not in use 2. Have replacement ready if needed 3. Revoke token 4. Monitor for errors 5. Update documentation ## API Integration ### Request Patterns **Synchronous Validation** For real-time signup forms: ```bash curl -X POST https://api.autheona.com/v1/public/verify \ -H "Authorization: Bearer TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email_address": "user@example.com", "show_results": true }' ``` - Fast response needed - Show results to user - Handle typo suggestions - Block invalid emails immediately **Asynchronous Validation** For bulk operations: - Use soft_check for performance - Process in background jobs - Batch requests within rate limits - Don't block user experience **Caching Strategy** Cache validation results: - Cache key: email address - TTL: 24 hours for valid emails - TTL: 1 hour for invalid emails - Bypass cache for high-value actions Benefits: - Reduced API calls - Faster responses - Lower costs - Better rate limit management ### Error Handling **Rate Limit Errors** Implement exponential backoff: 1. First retry: Wait 1 second 2. Second retry: Wait 2 seconds 3. Third retry: Wait 4 seconds 4. Fourth retry: Wait 8 seconds 5. Give up after 5 attempts **Timeout Handling** Set reasonable timeouts: - Connection timeout: 5 seconds - Read timeout: 10 seconds - Total timeout: 15 seconds Fallback strategy: - Allow signup on timeout (fail open) - Log timeout for investigation - Monitor timeout rates **Error Response Handling** Always check HTTP status: - 200: Process validation result - 400: Fix request parameters - 500: Retry with backoff, then fail open **Fail Open vs Fail Closed** Fail Open (Recommended): - Allow signup if API errors - Better user experience - No service dependency - Monitor error rates Fail Closed: - Block signup if API errors - Maximum security - Risk of blocking legitimate users - Use only for high-security requirements ### Performance Optimization **Minimize show_results** Only use when needed: - Don't enable for every request - Use for user-facing validations - Disable for background jobs - Cache results when enabled **Use soft_check Appropriately** Enable soft_check for: - Bulk imports - Background validation - Non-critical checks - Performance-critical paths Disable soft_check for: - Signup flows - Critical validations - When analytics needed - When domain data required **Parallel Requests** When validating multiple emails: - Batch within rate limits - Use connection pooling - Respect 10 requests/second limit - Implement proper queuing ### Monitoring **Track Metrics** Monitor: - API response times - Error rates by type - Rate limit hits - Validation pass/fail rates - Typo suggestion acceptance **Set Alerts** Alert on: - Error rate above 5% - Response time above 500ms - Rate limit errors - Unusual validation patterns **Review Analytics** Weekly: - Check validation pass rates - Review common errors - Identify domain patterns - Adjust rules if needed ## Rule Configuration ### Rule Selection **Start Conservative** Begin with stricter rules: - Easier to relax than tighten - Establishes baseline - Protects from day one - Can adjust based on data **Monitor Impact** Track for 1-2 weeks: - Rejection rates - User complaints - False positive patterns - Domain patterns **Adjust Gradually** Make one change at a time: - Change single rule - Monitor for 3-5 days - Measure impact - Document results - Repeat if needed ### Common Configurations **High Security** Enable: - Block Disposable Domains - Block Free Providers (if B2B) - Fraud Pattern Detection - Domain Age Signal - Risk Scoring - MX Record Check **High Conversion** Enable: - Typo Detection with Soft Warning - Fraud Detection with Soft Warning - Plus Addressing - Dot Variations - MX Record Check **Balanced** Enable: - Block Disposable Domains - Typo Detection with Suggestions - MX Record Check - Plus Addressing - Deliverability Score ### Rule Testing **Test Scenarios** Always test: - Valid common emails (gmail.com, outlook.com) - Typos (gmial.com, yaho.com) - Disposable domains - Role-based addresses - Edge cases for your industry **Regression Testing** Maintain test suite: - Known valid emails that should pass - Known invalid emails that should fail - Edge cases specific to your rules - Run tests before rule changes ## Security Best Practices ### API Security **Never Expose Tokens** - Backend only - never frontend - No client-side JavaScript - No mobile app hardcoding - Use backend proxy if needed **HTTPS Only** - Always use HTTPS - Never downgrade to HTTP - Validate SSL certificates - Monitor certificate expiration **Input Validation** Before calling API: - Basic format validation - Length checks - Character validation - Sanitize user input ### Data Privacy **Email Storage** - Don't log full emails unnecessarily - Hash emails when possible - Comply with GDPR/privacy laws - Document retention policies **Analytics Data** - soft_check when privacy critical - Review what data is stored - Implement data retention - Provide user data deletion **Compliance** - Review Autheona privacy policy - Understand data locations - Document your usage - Implement user data requests ## Billing Optimization ### Quota Management **Monitor Usage** Check regularly: - Current month usage - Projected end-of-month usage - Usage by project - Trends over time **Optimize Calls** Reduce unnecessary calls: - Cache validation results - Use soft_check when appropriate - Validate format client-side first - Deduplicate validation requests **Plan Appropriately** - Leave 20% buffer for growth - Upgrade before hitting limits - Consider seasonal variations - Plan for marketing campaigns ### Cost Control **Sandbox Testing** - Use sandbox for all development - Test rule changes in sandbox - Train new developers in sandbox - Sandbox calls are free **Smart Caching** Implement caching: - Cache valid emails longer (24 hours) - Cache invalid emails shorter (1 hour) - Invalidate cache on rule changes - Use cache for repeat users **Batch Operations** For bulk validation: - Use soft_check - Implement queuing - Spread over time - Stay within rate limits ## Development Workflow ### Local Development **Environment Setup** - Use sandbox project - Store tokens in .env files - Add .env to .gitignore - Document setup process **Testing** - Unit test validation logic - Mock API responses - Test error handling - Test rate limit scenarios ### Staging Environment **Configuration** - Mirror production rules - Use dedicated staging project - Separate tokens from production - Monitor staging analytics **Pre-Production Validation** Before deploying to production: - Test with real traffic patterns - Validate rule changes - Check error rates - Review performance ### Production Deployment **Deployment Checklist** 1. Test in sandbox thoroughly 2. Validate in staging 3. Document changes 4. Create new token if needed 5. Deploy to subset of users first 6. Monitor metrics closely 7. Roll out fully after validation **Rollback Plan** Always have rollback ready: - Keep old tokens active during transition - Document rollback steps - Test rollback procedure - Have on-call support ready ## Troubleshooting ### High Rejection Rates **Diagnose** Check: - Which rules are causing rejections - Common error codes - Domain patterns - User complaints **Fix** Consider: - Relaxing specific rules - Adding soft warning mode - Allowing plus addressing - Reviewing domain lists ### False Positives **Identify Patterns** Look for: - Legitimate domains blocked - Valid email formats rejected - User feedback - Common themes **Adjust Rules** Options: - Add domains to custom lists - Disable problematic rules - Use soft warnings instead - Create exception handling ### Performance Issues **Slow Response Times** Optimize: - Enable caching - Reduce show_results usage - Check network latency - Consider geographic routing **Rate Limit Hits** Solutions: - Implement request queuing - Add exponential backoff - Cache more aggressively - Upgrade plan if needed