API Keys

API keys authenticate your requests to the PageGun API. Think of them as your password for programmatic access — they give you full control over your account.

Why You Need an API Key

Every request to the PageGun API requires authentication. API keys:

Authenticate you — Prove you own the account
Authorize access — Grant permission to your projects and pages
Track usage — Count against your plan's rate limits
Audit activity — Appear in your dashboard logs

Creating Your First API Key

Step-by-Step Guide

Log in to your PageGun dashboard
Navigate to Settings → API Keys in the sidebar
Click the "Create New Key" button
Name your key descriptively:
- ✅ Good: Production Website, AI Content Agent, Development Testing
- ❌ Avoid: My Key, Key 1, Test
Copy immediately — You'll only see the key once for security

⚠️ Important: Store your key securely right away. If you lose it, you'll need to create a new one.

Multiple Keys for Multiple Use Cases

Consider creating separate keys for different purposes:

🏗️  Development    → pgk_live_dev_abc123...
🚀  Production     → pgk_live_prod_xyz789...
🤖  AI Automation  → pgk_live_agent_def456...
📊  Analytics      → pgk_live_analytics_ghi789...

Using Your API Key

Authentication Header

Include your API key in the Authorization header of every request:

curl -X GET "https://api.pagegun.com/projects" \
  -H "Authorization: Bearer pgk_live_your_key_here"

Environment Variables (Recommended)

Store your key as an environment variable to keep it secure:

# In your .env file
PAGEGUN_API_KEY=pgk_live_your_actual_key_here

# In your shell
export PAGEGUN_API_KEY="pgk_live_your_actual_key_here"

# Use in requests
curl -X GET "https://api.pagegun.com/projects" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"

SDK Usage

Coming soon: Official SDKs for popular languages will handle authentication automatically:

// Node.js (coming soon)
const pagegun = new PageGun(process.env.PAGEGUN_API_KEY);
const projects = await pagegun.projects.list();

# Python (coming soon)
import pagegun
client = pagegun.Client(os.environ['PAGEGUN_API_KEY'])
projects = client.projects.list()

Key Format & Recognition

PageGun API keys follow a consistent format for easy recognition:

pgk_live_[32_random_characters]

Examples:

pgk_live_a1b2c3d4e5f6789012345678901234
pgk_live_xyz789abc123def456ghi012jkl345

Why this format?

pgk = PageGun identifier
live = Production environment (vs future test keys)
Random suffix = Secure entropy

Security Best Practices

🔐 Keep Keys Secret

# ✅ DO: Use environment variables
PAGEGUN_API_KEY=pgk_live_xyz789...

# ❌ DON'T: Hard-code in your app
const apiKey = "pgk_live_xyz789..."; // Never do this!

# ❌ DON'T: Commit to Git
git add .env                         # This will expose your key!

🔄 Rotate Keys Regularly

Review quarterly — Check which keys are still needed
Delete unused keys — Clean up old development keys
Create new keys — Before deleting old ones to avoid downtime
Update everywhere — Remember to update all services using the old key

🏢 Separate Environments

Environment	Key Name	Usage
Development	`Dev Testing`	Local development, staging
Production	`Production App`	Live website, critical services
CI/CD	`GitHub Actions`	Automated deployments
AI Agents	`Content Bot`	Automated content generation

🚨 If Your Key is Compromised

Delete immediately in your PageGun dashboard
Create a new key with the same permissions
Update all services with the new key
Review recent activity in your dashboard logs

Rate Limits

Your API usage is limited by your plan:

Plan	Rate Limit	Burst Allowance
Free	60 requests/minute	100 requests
Pro	300 requests/minute	500 requests
Enterprise	Custom limits	Custom

Rate Limit Headers

Every API response includes rate limit information:

curl -I "https://api.pagegun.com/projects" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"

# Response headers:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200

Handling Rate Limits

When you exceed the limit, you'll receive a 429 Too Many Requests response:

{
  "statusCode": 429,
  "name": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 60 seconds."
}

Best practices for rate limiting:

Implement exponential backoff — Wait progressively longer between retries
Cache responses — Don't repeatedly fetch the same data
Batch operations — Use list endpoints instead of many individual requests
Consider upgrading — Pro plans have much higher limits

Common Authentication Errors

Invalid API Key

{
  "statusCode": 401,
  "name": "unauthorized",
  "message": "Invalid API key format or key not found."
}

Solutions:

Check your key format matches pgk_live_...
Verify the key exists in your dashboard
Ensure you're using the complete key

Missing Authorization Header

{
  "statusCode": 401,
  "name": "unauthorized",
  "message": "Authorization header missing."
}

Solution: Include the header in every request:

-H "Authorization: Bearer $PAGEGUN_API_KEY"

Deleted or Expired Key

{
  "statusCode": 401,
  "name": "unauthorized",
  "message": "API key has been deleted or expired."
}

Solution: Create a new API key in your dashboard.

Testing Your API Key

Verify your key works with a simple test request:

# Test authentication
curl -X GET "https://api.pagegun.com/projects" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json"

# Expected response:
{
  "data": [
    {
      "id": "proj_abc123",
      "name": "My Website",
      "domain": "mysite.pagegun.io",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

✅ Success: You see your projects listed.
❌ Error: Check the error message and solutions above.

Ready to start building? Check out our Quick Start guide to create your first page!

undefined