datadog-auth

name	datadog-auth
description	Troubleshoot Datadog API authentication issues (401/403 errors), understand API keys vs app keys, and configure correct regions. Use when hitting auth errors or setting up Datadog API access.

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 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 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