datadog.md

datadog

One connection is one Datadog organization. toolpass authenticates with an API key and a scoped application key, finds the user by email, reads the permissions carried by the user's roles, and for a monitor, dashboard, SLO or notebook reads the asset's restriction policy and its legacy restricted_roles and author fields. A user may change such an asset only when a role carries the write permission and the asset's restrictions, if any, name the user, one of the user's roles or teams, or the whole org. Nothing is written.

Credential

1. An API key of the organization (api_key).
2. An application key (credential) created for a dedicated service account or user and scoped to user_access_read, teams_read and the read scope of each asset type asked about: monitors_read, dashboards_read, slos_read, notebooks_read. Reading a restriction policy needs no named scope. An unscoped application key carries every permission of its creator, which is far more than toolpass needs.

toolpass probe validates the API key, lists one user (which proves user_access_read) and reminds you of the other scopes.

Connection

  - id: datadog-acme
    integration: datadog
    api_key: env:DATADOG_API_KEY
    credential: env:DATADOG_APP_KEY
    # url: https://api.datadoghq.eu     # default https://api.datadoghq.com; US3 api.us3.datadoghq.com, US5 api.us5.datadoghq.com, AP1 api.ap1.datadoghq.com

Key	Meaning
url	the site's API URL
api_key	sent as DD-API-KEY, env: or file:
credential	the application key, sent as DD-APPLICATION-KEY, env: or file:

Identity

GET /api/v2/users?filter=<email>&filter[status]=Active,Pending,Disabled, every page. The filter is a substring match on name, handle and email, so only the record whose email equals the address (ignoring case) is the user; none is user_not_found, two are user_ambiguous. A disabled user, or one whose status is still Pending, is denied every action. The identity carries the user's handle and the ids of the user's roles; each role's permissions come from GET /api/v2/roles/{id}/permissions, cached for five minutes. Groups sent by the caller are ignored.

Resources

Resource	Meaning
monitor:<id>	a monitor
dashboard:<id>	a dashboard (abc-def-ghi)
slo:<id>	a service level objective
notebook:<id>	a notebook
org	the organization, for permissions that are not about one asset

Actions

Action	Permission	Restriction relation	Resource
monitor.edit	monitors_write	editor	monitor
monitor.mute	monitors_downtime	editor (muting counts as editing a restricted monitor)	monitor
monitor.read	monitors_read	viewer	monitor
dashboard.edit	dashboards_write	editor	dashboard
dashboard.read	dashboards_read	viewer	dashboard
slo.edit	slos_write	editor	slo
notebook.edit	notebooks_write	editor	notebook
logs.read	logs_read_data		org
users.manage	user_access_manage		org
apikeys.manage	api_keys_write		org
raw:<permission>	that permission	on an asset: editor when it is one of the type's write permissions (monitors_write, monitors_downtime, dashboards_write, slos_write, notebooks_write), viewer otherwise	any

Evaluation

1. The permission: one of the user's roles must list it. On the org resource that is the answer.
2. The asset is read (GET /api/v1/monitor/{id}, /api/v1/dashboard/{id}, /api/v1/slo/{id}, /api/v1/notebooks/{id}); a 404 is resource_not_visible whatever the permission.
3. The restriction policy: GET /api/v2/restriction_policy/{type}:{id}. When it has bindings, the user must appear in a binding whose relation is the one needed or higher (viewer < editor; type-specific relations above editor count as editor) as user:<id>, role:<one of the user's roles>, team:<a team the user is a member of> (GET /api/v2/team/{id}/memberships, filtered by the user's email and compared by id) or org:<any>. A policy with no viewer binding restricts editing only: reads fall back to the permission.
4. Without a policy, the legacy fields: a monitor's or dashboard's restricted_roles must include one of the user's roles for an edit, except that a dashboard's author (author_handle) may always edit. Reads are not restricted by restricted_roles.

Decisions

Situation	toolpass answers
a role carries the permission and the asset has no restriction	allow
a role carries the permission and a binding at the relation names the user, a role, a team the user is on, or the org	allow, naming the principal kind
a role carries the permission and restricted_roles includes a role of the user, or the user authored the dashboard	allow
no role carries the permission	deny
the asset's restriction policy or restricted_roles name none of the user's principals	deny
disabled user, or a user whose invitation is still pending	deny
no user with the email	deny (user_not_found)
several users	unknown (user_ambiguous)
user record without disabled	unknown (unsupported)
the asset, a role of the user, or a team named by the policy answers 404	unknown (resource_not_visible)
401, 403 (Datadog answers 403 for an invalid key as well as for a missing scope)	unknown (credential_rejected)
429, 5xx, timeout	unknown (upstream_rate_limited / upstream_error / upstream_timeout)

Error bodies are never copied into a decision text.

Routes

The secure-tools toolkit maps a tool's requests to the API (api.<site>, the site's web host and its logs intake host, from url) to these actions; toolpass routes datadog prints the table.

Requests	Action and resource
a monitor, dashboard, SLO or notebook by id (/api/v1/monitor/{id}, ...)	its read or edit action on the asset (monitor.edit on monitor:123, raw:slos_read on slo:<id>), so restriction policies apply
creating or listing them	the permission on org (raw:monitors_write, raw:dashboards_read)
a restriction policy of one of those assets	the asset's edit action (changes) or read action
a downtime naming a monitor (v1 monitor_id, v2 monitor_identifier.monitor_id)	monitor.mute on the monitor
a downtime by scope or monitor tags, or changing or cancelling one by id; the downtimes matching a monitor (GET /api/v2/monitor/{id}/downtime_matches)	raw:monitors_downtime on org
searching or aggregating logs; an archive search's results	logs.read
reading API keys or any user's application keys, which returns the keys	raw:api_keys_read or raw:org_app_keys_read on org
searching spans; reading a trace (/api/v2/trace/{id}, /api/v2/pruned_trace/{id})	raw:apm_read on org
users, roles, API and application keys, service accounts, logs and metrics configuration, metric and event queries	the one permission the API description names for the operation, as raw:<permission> on org (users.manage and apikeys.manage where they are that permission)

Refused: a body that names a second asset (an id or data.id other than the path's, more than one dashboard or SLO in a bulk request); creating a user or service account with roles (assign them afterwards with POST /api/v2/roles/{id}/users); writes to assets whose restriction policies the integration does not read (synthetic tests, security rules, workflows, on-call, logs pipelines, ...); writes the API description gives no permission for, or several; sharing dashboards outside the org; the agent's own application keys and profile (/api/v2/current_user); data intake (metrics, events, logs), which needs the API key alone; and every other product's writes until a route maps them. Bodies are read as application/json only; a duplicated member or a compressed body is refused. Reads with no route are allowed and marked untrusted.

What it cannot see

• Self-elevation: a user with user_access_manage can add themselves to any restriction policy. toolpass answers for the policy as it stands, so such a user is denied until they do.
• Assets other than monitors, dashboards, SLOs and notebooks (synthetics tests, security rules, workflows, ...), which have restriction policies of their own but no action here yet; use raw:<permission> on org for their permissions alone.
• Log restriction queries, index-level log permissions, and RBAC on APM services.
• Team membership through team-links or provisioning that the memberships endpoint does not list.

Unverified

Marked # UNVERIFIED: in the code:

• Whether a monitor's creator keeps edit rights under restricted_roles the way a dashboard's author does. Datadog documents roles only for monitors, so the creator is not exempted.
• That a restriction policy without a viewer binding leaves viewing to the permission. The UI writes an explicit viewer binding for the org whenever it restricts an asset, which is why toolpass reads a policy without one as restricting editing only.

Assumed from Datadog's documentation rather than tested live: that the write permission is still required when a restriction policy grants editor ("the limitations are applied both in the UI and API"), and that GET /api/v2/restriction_policy/{id} answers 200 with empty bindings, not 404, for an asset without a policy (a 404 is treated the same).

Test

Unit tests run against a fake that serves users (paged), role permissions, monitors, dashboards, SLOs, notebooks, restriction policies and team memberships (paged), validating every request against Datadog's v1 and v2 OpenAPI descriptions (datadog-v1 and datadog-v2 in test/specs/fetch.sh). There is no live test; after configuring, run toolpass probe and one check for a user you know is allowed.