Authentication

All PocketDNS API requests require authentication using Bearer tokens. This guide covers authentication methods and security best practices.

API Key Authentication

Include your API key in the Authorization header for all requests:

Authorization: Bearer YOUR_API_KEY

Example Request

const response = await fetch('https://api.pocketdns.com/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user_identifier: 'unique-user-id-123',
    email: 'user@example.com'
  })
});

Environment-Specific Keys

Make sure to use the correct API key for your target environment:

Environment	Base URL	Key Type
Sandbox	https://api.sandbox.pocketdns.com	Sandbox API Key
Production	https://api.pocketdns.com	Production API Key

Never mix environments!

Using a production key with sandbox URLs (or vice versa) will result in authentication errors.

Security Best Practices

Server-Side Only

• ✅ DO: Store API keys on your server
• ✅ DO: Make API calls from your backend
• ❌ DON'T: Include API keys in client-side code
• ❌ DON'T: Commit API keys to version control

Secure Storage

Store your API keys securely using:

• Environment variables
• Secure configuration management systems
• Encrypted storage solutions

# Example environment variable
export POCKETDNS_API_KEY="your_api_key_here"

Network Security

• Always use HTTPS for API communications
• Implement proper request/response logging
• Set up monitoring for failed authentication attempts

Error Handling

Common Authentication Errors

Status Code	Description	Solution
401	Unauthorized - Invalid API key	Check your API key and environment
403	Forbidden - Insufficient permissions	Contact support to verify account status

Example Error Response

{
  "error": "Invalid API key"
}

Handling Auth Errors in Code

try {
  const response = await fetch('/api/v1/users', {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  });

  if (response.status === 401) {
    throw new Error('Invalid API key - check your credentials');
  }
  
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }
  
  const data = await response.json();
  return data;
  
} catch (error) {
  console.error('Authentication error:', error);
  // Handle error appropriately
}

API Key Management

Rotating Keys

Regularly rotate your API keys for security:

1. Generate a new API key in the partner dashboard
2. Update your application configuration
3. Test the new key in your staging environment
4. Deploy to production
5. Revoke the old key

Multiple Keys

You can create multiple API keys for different purposes:

• Development: For local development and testing
• Staging: For pre-production testing
• Production: For live applications
• CI/CD: For automated testing and deployment

INFO

Each API key can be given a descriptive name to help you manage them effectively.