Authentication

Learn how to authenticate your requests to the copyto.design API.

API Keys

All API requests require authentication using an API key. Keys are scoped to your account and can be managed from your dashboard.

Getting an API Key

1. Navigate to API Keys Dashboard
2. Click “Create API Key”
3. Optionally give it a descriptive name
4. Copy and securely store your key

Important: API keys are shown only once. If you lose a key, you’ll need to generate a new one.

Using API Keys

Header-based Authentication

The recommended method is to include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Example with cURL:

curl -X POST https://api.copyto.design/v1/convert \
  -H "Authorization: Bearer ct_sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"html": "<div>Hello</div>"}'

Example with JavaScript:

const response = await fetch('https://api.copyto.design/v1/convert', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ct_sk_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ html: '<div>Hello</div>' })
});

Example with Python:

import requests
 
response = requests.post(
  'https://api.copyto.design/v1/convert',
  headers={
    'Authorization': 'Bearer ct_sk_abc123...',
    'Content-Type': 'application/json'
  },
  json={'html': '<div>Hello</div>'}
)

Publishable Keys

Publishable keys (prefix: ct_pk_) are for client-side applications:

• Limited API access
• Safe to expose in browsers
• Rate-limited per key
• Good for demos and testing

ct_pk_xyz789uvw456...

Security Best Practices

Protect Your Keys

Never commit API keys to version control:

# .gitignore
.env
.env.local
config/secrets.yml

Use environment variables:

// .env
COPYTO_API_KEY=ct_sk_abc123...
 
// In your code
const apiKey = process.env.COPYTO_API_KEY;

Rotate Keys Regularly

We recommend rotating API keys every 90 days:

1. Generate a new key
2. Update your applications
3. Test the new key
4. Delete the old key

Monitor Usage

Regularly review API key usage in your dashboard:

• Check for unexpected usage patterns
• Set up alerts for high usage
• Monitor geographic distribution
• Review failed authentication attempts

Error Responses

Missing Authentication

{
  "success": false,
  "error": {
    "code": "MISSING_AUTH",
    "message": "Authorization header is required"
  }
}

HTTP Status: 401 Unauthorized

Invalid Key

{
  "success": false,
  "error": {
    "code": "INVALID_KEY",
    "message": "The provided API key is invalid"
  }
}

HTTP Status: 401 Unauthorized

Expired Key

{
  "success": false,
  "error": {
    "code": "KEY_EXPIRED",
    "message": "This API key has expired"
  }
}

HTTP Status: 401 Unauthorized

Rate Limiting

Rate limits are applied per API key:

Free Tier

• 100 requests per day
• 10 requests per minute
• 1 concurrent request

Pro Tier

• 10,000 requests per day
• 100 requests per minute
• 10 concurrent requests

Enterprise Tier

• Custom limits
• Dedicated infrastructure
• Priority support

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9995
X-RateLimit-Reset: 1640995200

Handling Rate Limits

When you exceed the rate limit, you’ll receive:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Try again later.",
    "retryAfter": 60
  }
}

HTTP Status: 429 Too Many Requests

Implement exponential backoff:

async function makeRequestWithBackoff(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

Next Steps

• Explore API Endpoints
• View code examples
• Check your usage dashboard