View Source

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:

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