Skip to main content

API Key Management

API keys provide programmatic access to GoDiffy's services. They're essential for integrating GoDiffy with CI/CD pipelines, automation scripts, and custom applications.

What are API Keys?​

API keys are authentication tokens that:

  • Authenticate your requests to the GoDiffy API
  • Authorize access to your sites and resources
  • Track API usage and rate limits
  • Enable automation and integrations
Security First

Treat API keys like passwords. Never commit them to version control or share them publicly.

Creating Your First API Key​

Via Dashboard​

  1. Navigate to Profile → API Keys section
  2. Click "Generate New Key" or "Create API Key"
  3. Enter a descriptive name:
    • ✅ Good: "GitHub Actions - Production", "CI Pipeline - Staging"
    • ❌ Avoid: "Key 1", "Test"
  4. Copy your API key immediately - it won't be shown again!
  5. Store it securely in your password manager or secrets vault

What You'll See​

After creation, you'll receive:

API Key: godiffy_sk_1234567890abcdef...
Created: 2024-01-15 10:30:00 UTC
Last Used: Never
One-Time Display

API keys are only shown once during creation. If you lose it, you'll need to create a new one.

Using API Keys​

Authentication Header​

Include your API key in the Authorization header:

curl https://api.godiffy.com/api/sites \
  -H "Authorization: Bearer godiffy_sk_YOUR_API_KEY"

Common Use Cases​

1. GitHub Actions​

Store as a repository secret:

# .github/workflows/visual-testing.yml
- name: Visual Regression Testing
  uses: godiffy/godiffy-action@v1
  with:
    api-key: ${{ secrets.GODIFFY_API_KEY }}
    site-id: ${{ secrets.GODIFFY_SITE_ID }}

Setup:

  1. Go to your GitHub repo → Settings → Secrets and variables → Actions
  2. Click "New repository secret"
  3. Name: GODIFFY_API_KEY
  4. Value: Your API key
  5. Click "Add secret"

2. Shell Scripts​

#!/bin/bash
# upload-screenshots.sh

API_KEY="godiffy_sk_YOUR_API_KEY"
SITE_ID="your-site-id"

# Upload images
for file in screenshots/*.png; do
  curl -X POST "https://api.godiffy.com/api/upload" \
    -H "Authorization: Bearer $API_KEY" \
    -F "site_id=$SITE_ID" \
    -F "file=@$file"
done

3. CI/CD Platforms​

GitLab CI:

# .gitlab-ci.yml
variables:
  GODIFFY_API_KEY: $GODIFFY_API_KEY  # Set in GitLab CI/CD variables

visual_testing:
  script:
    - curl -X POST https://api.godiffy.com/api/compare
      -H "Authorization: Bearer $GODIFFY_API_KEY"

Jenkins:

// Jenkinsfile
withCredentials([string(credentialsId: 'godiffy-api-key', variable: 'API_KEY')]) {
  sh '''
    curl -X POST https://api.godiffy.com/api/compare \
      -H "Authorization: Bearer $API_KEY"
  '''
}

CircleCI:

# .circleci/config.yml
jobs:
  visual_test:
    steps:
      - run:
          name: Visual Regression Test
          command: |
            curl -X POST https://api.godiffy.com/api/compare \
              -H "Authorization: Bearer $GODIFFY_API_KEY"

Managing API Keys​

Viewing Your Keys​

The API Keys page shows:

  • Key Name: Your descriptive label
  • Key Preview: Last 4 characters (e.g., ...abc123)
  • Created Date: When the key was generated
  • Last Used: Most recent API request timestamp
  • Status: Active or Revoked

Best Practices​

Naming Convention​

Use descriptive names that indicate:

  • Purpose: What the key is used for
  • Environment: Production, staging, development
  • Location: Which system uses it

Examples:

✅ "GitHub Actions - Production Site"
✅ "CI Pipeline - Staging Environment"
✅ "Local Development - John's Machine"
✅ "Jenkins - E2E Tests"

❌ "My Key"
❌ "Test"
❌ "Key 1"

Multiple Keys Strategy​

Create separate keys for:

  • Different environments (prod, staging, dev)
  • Different CI/CD pipelines
  • Different team members (for tracking)
  • Different applications

Example Setup:

Production:
  - "GitHub Actions - Main Site"
  - "Jenkins - Production Deploy"

Staging:
  - "GitHub Actions - Staging"
  - "Manual Testing - QA Team"

Development:
  - "Local Dev - Alice"
  - "Local Dev - Bob"

Rotating Keys​

Regularly rotate API keys for security:

  1. Create a new key with the same purpose
  2. Update your integrations with the new key
  3. Test the new key works correctly
  4. Revoke the old key after confirming everything works

Recommended Rotation Schedule:

  • Production keys: Every 90 days
  • Staging keys: Every 6 months
  • Development keys: Annually or when team members leave

Revoking API Keys​

When to Revoke​

Revoke a key immediately if:

  • ✋ Compromised: Key was exposed publicly
  • 👋 Team member left: Developer no longer needs access
  • 🔄 Rotating: Replacing with a new key
  • 🗑️ No longer used: Integration was deprecated

How to Revoke​

  1. Go to Profile → API Keys
  2. Find the key to revoke
  3. Click the trash icon or "Revoke" button
  4. Confirm the revocation
Immediate Effect

Revoked keys stop working immediately. Ensure you've updated all integrations before revoking.

API Key Limits​

Rate Limits by Plan​

PlanRequests per MinuteRequests per Day
Free601,000
Pro30010,000
EnterpriseCustomCustom

Checking Your Usage​

Monitor your API usage:

  • Dashboard: Shows current usage and limits
  • API Response Headers: Include rate limit information 
    X-RateLimit-Limit: 300
    X-RateLimit-Remaining: 287
    X-RateLimit-Reset: 1640000000

Handling Rate Limits​

If you hit rate limits:

// Implement exponential backoff
async function apiRequestWithRetry(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') || Math.pow(2, i);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

Troubleshooting​

For quick fixes to common API key issues (invalid keys, permissions, rate limits), see the consolidated Troubleshooting guide.

API Key Permissions​

Current Permission Model​

All API keys have full access to:

  • All sites in your account
  • All comparison operations
  • All upload operations
  • All report generation

Future: Scoped Permissions​

Coming soon - create keys with limited permissions:

  • Read-only: View sites and comparisons only
  • Upload-only: Upload images but not trigger comparisons
  • Site-specific: Access only specific sites

Next Steps​

Need Help?​