Datadog API Authentication

TL;DR

• Most v2 endpoints require two headers:
  • DD-API-KEY — org-scoped API key (32 hex chars)
  • DD-APPLICATION-KEY — application key VALUE (secret; 40 hex chars)
• Do not send key IDs (UUIDs) in headers. Always send the key values (secrets).
• Pick the correct region/site (e.g., us3.datadoghq.com) so the base is https://api.<DD_SITE>.
• Some APIs (including Incidents v2) do not support scoped app keys. Use an unscoped app key.

Terms at a Glance

Item	Example	Use in requests
API key (value)	aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa (32 hex)	Header DD-API-KEY
Application key (value, secret)	bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb (40 hex)	Header DD-APPLICATION-KEY
API key ID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (UUID)	Not for auth
Application key ID	yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy (UUID)	Not for auth

Regions / Sites

Region	API Base
US1	https://api.datadoghq.com
US3	https://api.us3.datadoghq.com
US5	https://api.us5.datadoghq.com
EU1	https://api.datadoghq.eu
AP1	https://api.ap1.datadoghq.com
AP2	https://api.ap2.datadoghq.com

Quick Validation

# Test API key only (no app key needed)
curl -sS -H "DD-API-KEY: $DD_API_KEY" https://api.$DD_SITE/api/v1/validate

# Or use the CLI
dd-cli validate

Common Errors

HTTP	Symptom	Likely cause	Fix
401	Unauthorized	Wrong app key value, wrong site/org, using key ID instead of value	Use the secret value, verify region
403	scoped app keys not supported	Using a scoped app key	Use an unscoped app key
403	Generic	Missing permission on owner's role	Adjust role permissions

Troubleshooting Checklist

1. API key valid? Run dd-cli validate
2. Region mismatch? Check which site returns 200:

   for site in us3.datadoghq.com datadoghq.com datadoghq.eu; do
     code=$(curl -s -o /dev/null -w "%{http_code}" -H "DD-API-KEY: $DD_API_KEY" "https://api.$site/api/v1/validate")
     echo "$site -> $code"
   done
   

3. Copy/paste artifacts? Strip whitespace:

   export DD_APP_KEY="$(printf %s "$DD_APP_KEY" | tr -d '\r\n')"
   

Scoped vs Unscoped Application Keys

• Unscoped: inherits permissions from its owner. Use when API doesn't support scoped keys.
• Scoped: limited to listed scopes. Use for least privilege when supported.

If you see "This API does not support scoped app keys," use an unscoped app key.

References

• Datadog API Authentication
• Incidents API