Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

Datadog Accounts, Sites, Organizations and API Keys

Understand Datadog sites (US1, EU1 and others), organizations, roles, API keys versus application keys, and how to keep keys safe when you automate.

Before you install anything you need a Datadog organization on the right site, and you need to know which kind of key does what. Mixing these up is the most common first-day problem: an Agent that sends data to the wrong site simply shows nothing, and a script with the wrong key type gets a 403.

Datadog cannot run here, so this lesson describes the console in words and uses a small Python stand-in to practice the rules around sites and keys.

Sites

Datadog runs several independent regional deployments called sites. Each has its own URL, and data sent to one site is invisible on another. Pick the site when you sign up; it also decides where your data is stored.

Site name Domain you browse Value of DD_SITE
US1 app.datadoghq.com datadoghq.com
US3 us3.datadoghq.com us3.datadoghq.com
US5 us5.datadoghq.com us5.datadoghq.com
EU1 app.datadoghq.eu datadoghq.eu
AP1 ap1.datadoghq.com ap1.datadoghq.com
AP2 ap2.datadoghq.com ap2.datadoghq.com
US1-FED app.ddog-gov.com ddog-gov.com

Check the address in your browser: if it says app.datadoghq.eu, every Agent and every API call must use datadoghq.eu. The Agent reads the site from DD_SITE or from the site: line of datadog.yaml; API calls go to api.<site>, for example https://api.datadoghq.eu.

Organizations and teams

Everything lives in an organization (org): hosts, dashboards, monitors, keys and users. Large companies sometimes use multi-organization accounts, with a parent org and child orgs to separate customers or business units, but one org is the normal starting point. Inside an org, Teams group people and the things they own, such as dashboards and monitors, so notifications and ownership are clear.

Users, roles and permissions

Datadog has built-in roles:

  • Datadog Admin: manages users, keys, billing and settings.
  • Datadog Standard: creates and edits dashboards, monitors and most content.
  • Datadog Read Only: views but does not change.

You can add custom roles with fine permissions (for example "can read logs but not archives"). Prefer SAML single sign-on for company accounts and give people the smallest role that lets them work.

API keys and application keys

Datadog uses two different credentials:

  • An API key identifies your organization. The Agent and any code that sends data (metrics, logs, events) uses it. It is a 32-character hexadecimal string.
  • An application key identifies a user or service account and carries that principal's permissions. Code that reads or changes things through the API (list monitors, create a dashboard, query metrics) needs both an API key and an application key. It is a 40-character string.
  • A client token is a separate, public-safe credential used by browser and mobile SDKs (RUM, browser logs). It is visible in page source, so it can only send data.

You create keys in Organization Settings (the API Keys and Application Keys pages). Names matter: create one API key per environment or per tool (agent-prod, terraform-ci) so you can rotate one without breaking everything. Application keys can be given scopes, limiting what they may do, and are best created for a service account rather than a person so they survive staff changes.

On the wire the keys travel as HTTP headers:

Terminal
curl -s -X GET "https://api.datadoghq.com/api/v1/validate" \
  -H "DD-API-KEY: ${DD_API_KEY}"

The validate endpoint answers {"valid": true} for a good API key. Calls that read or modify objects add a second header, DD-APPLICATION-KEY.

Never commit keys to Git, bake them into images, or paste them into front-end code (except the client token, which is meant to be public). Keep them in a secret store or CI secret and inject them as environment variables. If a key leaks, revoke it in Organization Settings and create a new one; there is no way to un-leak it.

Python Stand-in: site and key sanity checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The shapes in the checker are a convenience for catching typos, not a security check: only Datadog can tell you whether a key is valid.

Python Stand-in: which credential does a call need?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Good habits

  1. Use the site closest to your users and compliance needs, and record it in your runbook.
  2. One key per purpose; name them clearly; rotate on a schedule.
  3. Put application keys on service accounts with the minimum scopes.
  4. Turn on SSO and remove ex-employees promptly.
  5. Watch Audit Trail (where available) to see who created or changed keys.

If you installed an Agent and see nothing, the first two things to check are DD_SITE and the API key. The next lesson walks through a first install: your first host.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Your browser shows app.datadoghq.eu. What should DD_SITE be?

    DD_SITE is the domain without the app. prefix; for EU1 it is datadoghq.eu.
  2. 2. Which credential does the Agent need to send metrics?

    The API key identifies your organization and authorizes data intake.
  3. 3. A script that creates monitors through the API needs

    Management endpoints require DD-API-KEY and DD-APPLICATION-KEY.
  4. 4. Which credential is safe to appear in browser source code?

    Client tokens are designed for public SDKs and can only send data.

Summary

  • Datadog sites are separate regions; data on one is invisible on another.
  • An organization holds your hosts, dashboards, monitors, users and keys.
  • API keys send data; application keys (with an API key) manage objects; client tokens are public and send-only.
  • Use one key per purpose, service accounts for application keys, and revoke leaked keys at once.

Next: Your First Host: Installing the Agent