OAuth client missing DBM scope — `pup dbm samples search` always 403 with `built_in_features`

[naofumi-fujii]

Is your feature request related to a problem?

pup dbm samples search always returns 403 Forbidden under OAuth (pup auth login), even on a freshly re-authenticated session that already carries every default scope:

HTTP 403 Forbidden: {"errors":["Missing required permission: 'built_in_features'"]}

Root cause: the DBM samples endpoint (/api/v1/logs-analytics/list?type=databasequery) requires the built_in_features permission, which is not exposed as a Datadog OAuth scope. The same underlying endpoint accepts OAuth for plain logs calls (without ?type=databasequery), but the DBM-typed variant is gated by a permission that OAuth tokens cannot carry.

This forces a fallback to API + App key auth (DD_API_KEY / DD_APP_KEY, with the App key required to be unscoped — Datadog's DBM API guide explicitly states the scope is "only available on unscoped application keys"), which defeats the OAuth session model that pup otherwise provides — particularly painful for orgs with an SSO-only / no-long-lived-credentials policy.

This is the DBM analogue of #437 / #443 (AWS / GCP cloud-configuration scopes).

Repro

$ pup --version
pup 0.55.0

$ pup auth login   # standard interactive flow, defaults
$ pup auth status | jq '.scopes | length'
82

# logs against the same endpoint family work fine
$ pup logs search --query "service:my-service" --from 1h --limit 1 | jq '.data | length'
1

# DBM, however, 403s
$ pup dbm samples search \
    --query 'dbm_type:activity source:mysql @duration:>10s host:my-rds-host project:my-project' \
    --from 1h --limit 10
Error: failed to search DBM query samples: POST https://api.datadoghq.com/api/v1/logs-analytics/list?type=databasequery failed (HTTP 403 Forbidden): {"errors":["Missing required permission: 'built_in_features'"]}

A session with logs_read_data granted (verified in pup auth status) still gets 403 from pup dbm samples search, so the existing logs scope does not cover the DBM-typed variant of the same endpoint.

Tried passing the scope explicitly

Following the pattern from #437, I tried teaching pup about built_in_features and re-logging in:

1. Patched src/auth/types.rs to add "built_in_features" to default_scopes() and all_known_scopes().
2. Built and ran pup auth login --scopes built_in_features,....
3. Result:

⏳ Waiting for authorization...
Error: OAuth error: invalid_scope:

Datadog's OAuth IdP rejects built_in_features as an unknown scope. So the gap is on the server side — the scope simply is not part of the OAuth provider's catalogue today, regardless of what pup requests.

Describe the solution you'd like

Coordinate with the Datadog OAuth provider to expose a granular DBM scope (e.g. database_monitoring_read, by analogy with azure_configuration_read / aws_configuration_read) and register it in pup's OAuth client manifest so it can be requested at login.

DBM-related scopes pup currently knows (extracted from pup auth status JSON):

Scope	Known to pup?	Granted by Datadog OAuth IdP?
logs_read_data	✅	✅ (but does not cover ?type=databasequery)
built_in_features	❌ Unknown scope ignored	❌ invalid_scope from IdP
database_monitoring_read (hypothetical)	❌	❌

The exact scope name is up to you — database_monitoring_read is a guess by analogy with azure_configuration_read. Alternatively, relaxing the ?type=databasequery route to accept logs_read_data would also resolve this, since it's literally the same endpoint family.

Describe alternatives you've considered

• API + App key auth (unscoped App key + DD_API_KEY + DD_APP_KEY): works, but requires an unscoped (i.e. full-permission) App key per Datadog's DBM API guide. For orgs with an OAuth/SSO-only policy this is a major exception with significant governance overhead (rotation, vaulting, dedicated service account, etc.).
• --scopes built_in_features: silently dropped as "Unknown scope ignored" today. Adding it to all_known_scopes() and re-logging in surfaces an invalid_scope error from the IdP (verified — see "Tried passing the scope explicitly" above).
• Re-using existing scopes (logs_read_data, logs_read_index_data): granted in the session, but the DBM-typed variant of the endpoint still returns 403 — the route is gated by built_in_features specifically, not by the logs scope.
• UI-only access: the Datadog UI sees DBM samples just fine over SSO, confirming the underlying capability exists; only the OAuth-token path is blocked.

Additional context

PR #443 is the precedent for this kind of change — the AWS / GCP equivalent. That PR notes:

Without this, pup cloud {aws,gcp} list 401s even after Datadog enables OAuth on the underlying routes, because pup's OAuth client doesn't request the right scopes at login. Also required server-side configuration updates, which were applied separately.

The DBM situation is the same shape: a pup-side scope addition is necessary but not sufficient — the Datadog OAuth provider must also be taught to issue the scope. Filing this issue early so the server-side work can be tracked alongside.

Happy to test pre-release / staging builds or provide more diagnostics.

Proposed command syntax (if applicable)

No new commands. The existing pup dbm samples search gains working coverage under OAuth:

pup dbm samples search \
  --query 'dbm_type:activity source:mysql @duration:>10s' \
  --from 1h --limit 10

And the login flow can request the new scope when needed:

pup auth login --scopes database_monitoring_read,...

[srosenthal-dd]

I'm taking a look!

[srosenthal-dd]

This is trickier than the AWS/GCP scenario. I'm discussing with the DBM team how to fix it.