Skip to main content

Datadog API and Application Token Setup Guide

This comprehensive guide walks you through creating and configuring API Keys and Application Keys for Datadog integration, including proper scope assignment for different API functionalities.

Overview​

Datadog uses a dual authentication system that requires both an API Key and an Application Key for programmatic access:

  • API Key: Identifies your organization and provides basic access to Datadog APIs
  • Application Key: Provides additional permissions and scoping for specific operations

Both keys are required for all API requests to Datadog endpoints.

Prerequisites​

  • Access to a Datadog account with administrator privileges
  • Organization settings permissions to create and manage API keys
  • Understanding of the specific API operations you need to perform

Part 1: Creating an API Key​

Step 1: Navigate to API Keys Section​

  1. Log in to Datadog and access your organization dashboard
  2. Click on "Organization Settings" in the top navigation bar
  3. Navigate to the ACCESS section in the left sidebar
  4. Click on "API Keys" to access the API key management interface

Step 2: Create New API Key​

  1. Click the "New Key" button (blue plus icon) in the top-right corner
  2. Enter a descriptive name for your API key (e.g., "AI Gateway Integration - Production")
  3. Click "Create Key" to generate your new API key

Step 3: Copy and Secure Your API Key​

  1. Copy the generated API key immediately - it will only be shown once
  2. Store it securely in your password manager or secure configuration system
  3. Note the Key ID for reference and management purposes

⚠️ Security Warning: API keys provide access to your Datadog data. Never commit them to version control or share them publicly.

Part 2: Creating an Application Key​

Step 1: Navigate to Application Keys Section​

  1. From Organization Settings, navigate to the ACCESS section
  2. Click on "Application Keys" in the left sidebar
  3. Review existing application keys to avoid duplicates

Step 2: Create New Application Key​

  1. Click the "New Key" button (blue plus icon)
  2. Enter a descriptive name (e.g., "aigateway-key" or "API Integration Key")
  3. Click "Create Key" to generate the application key

Step 3: Initial Key Creation​

After creation, your application key will have limited default permissions and will be marked as "SCOPED", indicating that specific permissions need to be assigned.

Part 3: Configuring Application Key Scopes​

This is the most critical step for enabling different Datadog API functionalities.

Step 1: Edit Key Scope​

  1. Click on your newly created application key from the list
  2. Click "Edit Key Scope" or navigate to the key's scope management interface
  3. Review the available scope categories and permissions

Step 2: Understanding Scope Categories​

Datadog organizes permissions into several key categories:

API and Application Keys​

  • api_keys_read - List and retrieve API key values
  • api_keys_write - Create and rename API keys
  • api_keys_delete - Delete API keys
  • org_app_keys_read - View application keys in organization
  • org_app_keys_write - Manage application keys in organization
  • user_app_keys - View and manage user's application keys

APM (Application Performance Monitoring)​

  • apm_apdex_manage_write - Set Apdex T values on services
  • apm_api_catalog_read - View API catalog and definitions
  • apm_api_catalog_write - Add, modify, and delete API catalog definitions
  • apm_generate_metrics - Create custom metrics from spans

Step 3: Essential Scopes for API Integration​

For comprehensive Datadog API integration, select these key scopes:

Core API Access (Always Required)​

  • ✅ api_keys_read - Required for API key management
  • ✅ user_app_keys - Required for application key management

Dashboard Management​

  • ✅ dashboards_read - List and retrieve dashboards
  • ✅ dashboards_write - Create, update, and delete dashboards
  • ✅ dashboards_public_share - Generate public dashboard URLs (if needed)

Monitor Management​

  • ✅ monitors_read - List and retrieve monitors
  • ✅ monitors_write - Create, update, and delete monitors
  • ✅ monitors_downtime - Manage monitor downtimes (mute/unmute)

Metrics Access​

  • ✅ metrics_read - Query timeseries data and list metrics
  • ✅ metrics_write - Submit custom metrics
  • ✅ timeseries_query - Query historical metric data

User and Role Management​

  • ✅ users_read - List and retrieve user information
  • ✅ roles_read - List and retrieve role information
  • ✅ org_management - Organization management permissions (if needed)

Logs Management (Optional)​

  • ✅ logs_read_data - Read log data
  • ✅ logs_read_index_data - Read logs from any index
  • ✅ logs_modify_indexes - Update log indexes (if needed)

Security Monitoring (Optional)​

  • ✅ security_monitoring_signals_read - Read security monitoring signals
  • ✅ security_monitoring_rules_read - Read security monitoring rules

For a comprehensive API integration, select these scopes:

✅ API and Application Keys:
   - api_keys_read
   - user_app_keys
   
✅ Dashboard Management:
   - dashboards_read  
   - dashboards_write
   
✅ Monitor Management:
   - monitors_read
   - monitors_write
   
✅ Metrics:
   - metrics_read
   - timeseries_query
   
✅ User/Role Access:
   - users_read
   - roles_read
   
✅ APM (if using APM features):
   - apm_api_catalog_read
   - apm_generate_metrics ✓ (as shown selected in screenshot)

Step 5: Save Scope Configuration​

  1. Review your selected scopes to ensure all required permissions are included
  2. Click "Save" to apply the scope configuration
  3. Verify the application key now shows the correct scopes in the key listing

Regional Endpoints​

Datadog has different API endpoints for different regions. Ensure you're using the correct endpoint:

RegionAPI Endpoint
US1https://api.datadoghq.com
US3https://api.us3.datadoghq.com
US5https://api.us5.datadoghq.com
EU1https://api.datadoghq.eu
AP1https://api.ap1.datadoghq.com
US1-FEDhttps://api.ddog-gov.com

Security Best Practices​

Key Management​

  • Rotate keys regularly (every 90 days recommended)
  • Use different keys for different environments (dev, staging, production)
  • Implement key rotation procedures in your deployment processes
  • Monitor key usage through Datadog's audit logs

Scope Management​

  • Apply principle of least privilege - only assign required scopes
  • Regularly audit application key scopes and remove unnecessary permissions
  • Create dedicated keys for specific use cases rather than using one key for everything
  • Document the purpose and scopes of each application key

Environmental Security​

  • Use environment variables for key storage
  • Never commit keys to version control
  • Use secure secret management systems (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Implement key masking in logs and error messages

Conclusion​

With properly configured API and Application keys, you now have secure, scoped access to Datadog's comprehensive API ecosystem. Remember to:

  1. Keep your keys secure and rotate them regularly
  2. Use minimal required scopes for security
  3. Test your configuration before production deployment
  4. Monitor key usage and audit permissions regularly

Your Datadog integration is now ready for production use with dashboard management, monitoring, metrics, and user management capabilities.

Additional Resources​

Need Help? Contact your Datadog administrator or refer to Datadog's support documentation for additional assistance.