API Key Management

This guide covers managing API keys in Agility CMS, including key types, security, and best practices.

API Key Types

Agility CMS provides three types of API keys:

Fetch Key

Purpose: Access published content in production

Use Case:

• Production websites and applications
• Public-facing content access
• Standard content delivery

Security:

• Can only access published content
• Cannot access draft content
• Safe for client-side use (with restrictions)

Preview Key

Purpose: Access draft content for preview

Use Case:

• Preview mode in applications
• Development environments
• Content editor previews

Security:

• Can access draft and published content
• Should be kept secure
• Use server-side only

Security Key

Purpose: Validate preview keys

Use Case:

• Checking the preview key when your site switches into preview mode

Security:

• Must be kept secret
• Use server-side only
• Never expose publicly

The Security Key is not used for webhooks. Agility never sends it with a webhook. To verify that a webhook request came from Agility, tick Enable secure delivery on the webhook in Settings → Webhooks. Each webhook then gets its own whsec_ signing secret. See Verifying Signed Webhooks.

Managing API Keys

Viewing API Keys

1. Navigate to Settings → API Keys
2. View current keys:
   • Fetch Key
   • Preview Key
   • Security Key

Regenerating API Keys

1. Navigate to Settings → API Keys
2. Click "Regenerate" for the key you want to regenerate
3. Important: Update all applications using the key
4. Update environment variables in all environments

Key Permissions

API keys have different permissions:

• Fetch Key: Read-only access to published content
• Preview Key: Read access to draft and published content
• Security Key: Preview key validation only

API Key Security

Best Practices

1. Never Commit Keys: Never commit API keys to version control
2. Use Environment Variables: Store keys in environment variables
3. Rotate Regularly: Rotate keys periodically
4. Different Keys for Environments: Use different keys for dev/staging/production
5. Monitor Usage: Monitor API key usage for suspicious activity
6. Restrict Access: Limit who has access to API keys

Key Storage

Environment Variables:

AGILITY_API_FETCH_KEY=your-fetch-key
AGILITY_API_PREVIEW_KEY=your-preview-key
AGILITY_SECURITY_KEY=your-security-key

Never:

• Commit keys to git
• Share keys publicly
• Hardcode keys in code
• Log keys in console

API Key Usage

Fetch Key Usage

// Production content access
const sdk = agility.getApi({
  guid: process.env.AGILITY_GUID,
  apiKey: process.env.AGILITY_API_FETCH_KEY,
  isPreview: false
})

Preview Key Usage

// Draft content access
const sdk = agility.getApi({
  guid: process.env.AGILITY_GUID,
  apiKey: process.env.AGILITY_API_PREVIEW_KEY,
  isPreview: true
})

Security Key Usage

Your site's preview route uses the Security Key to validate the preview key it receives before it turns on preview mode. Keep it in a server-side environment variable such as AGILITY_SECURITY_KEY.

To secure a webhook endpoint, use that webhook's whsec_ signing secret instead. Verifying Signed Webhooks has the verification code.

Troubleshooting

Invalid API Key

Issue: API calls return 401 Unauthorized

Solutions:

• Verify key is correct
• Check for typos or extra spaces
• Ensure correct key type (fetch vs preview)
• Verify key hasn't been regenerated

Key Regeneration

Issue: Need to regenerate compromised key

Steps:

1. Regenerate key in Agility CMS
2. Update environment variables
3. Update all applications
4. Test API access
5. Monitor for issues

---

Next: Webhooks - Webhook configuration