Skip to main content

​
About Datadog

Datadog is an observability and monitoring platform covering metrics, logs, monitors, dashboards, APM, and security monitoring. Serval connects to a Datadog organization using a Datadog API key plus an Application key, both stored as secrets and attached to every request Serval makes on your behalf. You select your Datadog site (US1, US3, US5, EU, AP1, or GOV) by entering the matching API domain, and an Instance Name distinguishes multiple Datadog connections on the same team. Authentication: Datadog API key + Application key (custom header authentication). Both keys are stored as secrets and injected on every request as the DD-API-KEY and DD-APPLICATION-KEY headers. There is no OAuth flow and no token refresh - the keys are used as-is until you rotate them by editing the connection. Data sync: On-demand only. Serval calls the Datadog API when a workflow step runs - there is no background sync, and the integration ships no pre-installed workflows.

​
What the Datadog integration enables

Anything defined in the Datadog API can be accessed through Serval.

​
Get your credentials

Serval needs two keys from Datadog: an API key (authenticates the connection to your organization) and an Application key (authorizes access to data like metrics, logs, and monitors). Both are created in Datadog under Organization Settings - see Datadog: API and Application Keys for the official guide.
1

Log in to Datadog

Log in to your Datadog account. For the US1 site that is https://app.datadoghq.com; if your organization is on another site, use your site’s own app domain.
2

Create an API key

Navigate to Organization Settings > API Keys, click New Key, name it (e.g. “Serval Integration”), and copy the generated API key.
3

Create an Application key

Navigate to Organization Settings > Application Keys, click New Key, name it (e.g. “Serval App Key”), optionally edit its scopes, and copy the generated application key.
4

Note your Datadog site's API domain

Check your Datadog dashboard URL to identify your site, then note the matching API domain: api.datadoghq.com (US1), api.us3.datadoghq.com (US3), api.us5.datadoghq.com (US5), api.datadoghq.eu (EU), api.ap1.datadoghq.com (AP1), or api.ddog-gov.com (GOV).
The Application key inherits the permissions of the Datadog user who creates it. Create it as a user (or service account) with the permissions your workflows need - if that user’s permissions are later reduced, what Serval can access narrows with them. See the Datadog RBAC permissions list for what each permission grants.
Getting the API domain right matters more than anything else on this page. Your keys only exist on your organization’s site, so a US3 organization’s keys will never work against the US1 domain.

​
Connect in Serval

All four fields are required. Leaving the API Domain or Instance Name blank stops submission with “This field is required”, and a submission missing either key is rejected by Serval with an error stating that the key is required.
1

Enter the API Domain

Enter your Datadog site’s API host without https://, e.g. “api.datadoghq.com”. The helper text lists the valid options: “Your Datadog API domain (without https://). Common options: api.datadoghq.com (US1), api.us3.datadoghq.com (US3), api.us5.datadoghq.com (US5), api.datadoghq.eu (EU), api.ap1.datadoghq.com (AP1), api.ddog-gov.com (GOV)”. Anything else is rejected with “Must be a valid Datadog API domain (e.g., api.datadoghq.com, api.us3.datadoghq.com, api.datadoghq.eu)”.
2

Enter the API Key

Paste the API key you created. This is a password-type field with the helper text “Your Datadog API key. You can generate one from Organization Settings > API Keys”.
3

Enter the Application Key

Paste the Application key you created. This is a password-type field with the helper text “Your Datadog application key. Required for accessing metrics, logs, and other data. Generate from Organization Settings > Application Keys”.
4

Enter an Instance Name

Give the connection a display name, e.g. “Production”. The helper text reads “A name to identify this Datadog instance (e.g., ‘Production’, ‘Engineering’). Required to distinguish between multiple Datadog connections.”
5

Submit the form

Click Submit to create the connection. Serval stores both keys as secrets and verifies the connection with a health check against your Datadog site.
When editing an existing Datadog connection, any field you leave blank keeps its current value - only fields you fill in are overwritten. To rotate just the API key, fill in only that field. For security, existing key values are never displayed in the edit form.

​
Verifying the connection

When the connection is created, Serval runs a health check that confirms your API key is valid and your Datadog site is reachable. The integration also includes four named health-check workflows you can run at any time:
  • Validate Datadog API Connection - confirms the API key is valid and the API is reachable. This check exercises only the API key, not the Application key. On success: “Successfully authenticated with Datadog API”. On failure: “Unable to connect to Datadog API. Please verify your API token is valid and has the necessary permissions.”
  • Check Datadog Organization Access - verifies Serval can read your organization details. On success: “Successfully accessed organization: [organization name]”. If the API is reachable but returns no organization data: “Could not retrieve organization information from Datadog”. On failure: “Failed to access organization information. Please verify your API token has the necessary permissions.”
  • Check Datadog Metrics API Access - counts metrics active in the last hour. On success: “Successfully accessed Metrics API. Found [number] active metrics.” On failure: “Failed to access Metrics API. Please verify your API token has the necessary permissions for metrics access.”
  • Check Datadog Logs API Access - counts your log pipelines. On success: “Successfully accessed Logs API. Found [number] log pipelines.” On failure: “Failed to access Logs API. Please verify your API token has the necessary permissions for logs access.”
A green connection check does not prove the Application key works - the initial health check and “Validate Datadog API Connection” only test the API key. If workflows get permission errors while the connection looks healthy, run the Organization, Metrics, and Logs health checks, which do exercise the Application key.

​
Gotchas and troubleshooting

The API Domain is a free-text field validated against exactly six api.* domains - it is not auto-detected. If your Datadog organization is on US3 or US5 but you enter api.datadoghq.com (US1), the form accepts it and the connection saves, but every API call fails authentication because your keys only exist on your organization’s site. Check your Datadog dashboard URL (e.g. us3.datadoghq.com) and use the matching API domain. Enter it without https:// - the form requires the bare host, and Serval also strips any https:// or http:// prefix defensively.
The install-time health check and the “Validate Datadog API Connection” workflow only verify the API key. Reading metrics, logs, monitors, and most other data also requires a valid Application key. If workflow calls return permission errors (403) while the connection looks healthy, check the Application key - and run the Organization, Metrics, and Logs health-check workflows, which do exercise it.
What a Serval workflow can read or write in Datadog is bounded by the role and permissions of the Datadog user who created the Application key. Create the key from a user or service account with the permissions your workflows need, and remember that access narrows if that user’s permissions are later reduced.
When updating an existing Datadog connection, any field left blank (API Key, Application Key, API Domain, or Instance Name) retains its current value - only non-empty fields are overwritten. To rotate just the API key, fill in only that field. Existing key values are never displayed in the edit form.
Newer (v2) Datadog APIs, such as log event search, page through results with a cursor: each response includes a cursor value that must be passed into the next request until none is returned. Older (v1) APIs use offset-based paging instead. Some operations also require a specific request method - log search uses POST, not GET. Mixing these up is a common cause of missing results in workflows.
The connection’s identity is built from the API domain plus the Instance Name, which is what lets you connect multiple Datadog organizations (or multiple key sets) to the same team. Pick a stable, meaningful name like “Production” - it is also the connection’s display name.
Need help? Contact support@serval.com for assistance with your Datadog integration.