Best Practices for Handling API Keys

API keys are powerful credentials that provide access to your Notion workspace through our Public API. If these keys fall into the wrong hands, they can pose serious security risks to your integrations, data and workspace.

Why Leaked API Keys Are Dangerous

When your Notion API key is exposed, malicious actors could potentially:

• Access sensitive data: Read all pages, databases, and content in your workspace
• Modify or delete content: Make unauthorized changes to your workspace data
• Export your data: Download and steal your intellectual property
• Perform actions on your behalf: Create, update, or delete pages and databases
• Access user information: View workspace members and their permissions

The scope of access depends on the permissions granted to the integration that owns the API key, but even limited access can be dangerous in the wrong hands.

Best Practices for API Key Security

NEVER share your API keys

• Keep your API key private: Treat your API key like your personal password—don’t share it with anyone. If others need access, they should request their own key.
• Never post your key publicly: Avoid sharing your API key in public spaces such as forums, emails, or support tickets, with the Notion support team.
• Be careful with third-party tools: Uploading your API key to external services will provide your key to those services. Only share your key with trusted services. Always store your API key as an encrypted secret when working with third-party platforms. Never put your key directly into code or configuration files - use environment variables!

Use Environment Variables

Never hardcode API keys directly in your source code. Instead, use environment variables:

# .env file (never commit this file)
NOTION_API_KEY=ntn_abc123def456ghi789jkl012mno345pqr

// In your code
const notion = new Client({
  auth: process.env.NOTION_API_KEY,
});

Secure Your Environment Files

• Add .env files to your .gitignore to prevent accidental commits
• Use different API keys for development, staging, and production environments
• Store production keys in secure secret management systems like AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault

Implement Secret Scanning

Use tools like GitLeaks, Detect Secrets, or Trufflehog to automatically detect and prevent the commitment of sensitive information like API keys to your repositories. These tools can:

• Scan your codebase for potential secrets before commits
• Integrate with CI/CD pipelines for continuous scanning
• Alert developers when secrets are accidentally committed

Regular Key Rotation

• Rotate API keys on a schedule and set calendar reminders to do so
• Immediately rotate keys when team members with access leave
• Keep an inventory of all API keys and their purposes

What Should I Do If I Suspect My API Key Has Been Compromised?

If you suspect that your API key may be compromised, we recommend taking action immediately:

Step 1: Revoke the Compromised Key

1. Log into your Notion account
2. Go to Settings & members → Connections → Develop or manage integrations
3. Find the integration with the compromised key
4. Click “Refresh” on your integration

Step 2: Generate a New API Key

Rotate the compromised key by clicking Refresh in your integrations page at https://www.notion.so/profile/integrations update your applications with your new key.

Step 3: Review Recent Activity

1. Check your workspace for any suspicious activity
2. Review recent changes to pages and databases
3. Look for any unauthorized integrations in Settings & members → Connections

Step 4: Update Your Applications

• Replace the old API key in all your applications and environments
• Test that your integrations are working with the new key
• Remove the old key from any configuration files or documentation

Getting Help

If you need assistance with API key security or suspect unauthorized access, contact Notion support at [email protected]