Skip to main content

Set Integration Credentials (admin)

Requires admin-scoped API key

This tool is only available when authenticated with an admin-scoped Phoenix API key. User-scoped keys never see it in tools/list and receive 403 forbidden_admin_scope if they try to call it directly. See Admin operations overview for details.

Set or rotate the credential for an integration. Upserts the configured_integrations row — activation if no row existed, rotation if it did.

Tool key: admin_set_integration_credentials

Parameters​

NameTypeRequiredDefaultDescription
integration_keystringYes–Catalog key for the integration (e.g., 'hginsights_v2', 'salesforce'). 1–255 chars.
valuestringYes–Credential value to store. Treated as a secret — never echoed in responses, redacted from telemetry. 1–8192 chars.

Required Integrations​

None.

Output​

{
  "key": "hginsights_v2",
  "isConfigured": true,
  "hasCredentials": true,
  "updatedAt": "2026-04-29T14:00:00.000Z"
}

The value is not echoed back. Whether the call activated a new integration or rotated an existing one is visible in the audit log (metadata.wasUpdate: true for rotations).

How It Works​

  1. Org slug is derived from the API key.
  2. The catalog entry for integration_key is resolved — 404 integration_not_found if missing, 400 integration_disabled if the catalog entry is disabled.
  3. If a per-integration validator is registered, it runs against the value before persisting. Rejection returns 400 invalid_credentials with the validator's message; the existing row is left intact.
  4. The row is upserted with a single SQL statement using Postgres INSERT … ON CONFLICT (integration_key) DO UPDATE. The wasUpdate flag in the audit log comes from the same statement (xmax), eliminating a TOCTOU race.
  5. The MCP org-context cache is invalidated so the next handshake or tool call reads the new value.
  6. For TrustRadius specifically, the aggregator credentials are synced in surface mode — a sync failure returns 500 tool_setup_failed so the caller can retry.
  7. A row is written to webapp_org_admin_audit_log with action set_integration_credentials, target_type integration, target_id = integration_key, metadata { wasUpdate: boolean }.

Sensitive parameter handling​

The value parameter is declared sensitive (getSensitiveParameterKeys() => ['value']). Before any telemetry write, the metering layer replaces the value field in the parameter object with the literal string '<redacted>'. This applies to:

  • tool_metering.metadata.parameters (analytics table).
  • Structured log payloads written via the MCP API logger.

The actual tool execution still receives the real value — redaction is strictly downstream of execute.

Use Cases​

  • IT provisioning script activates Salesforce on a new org.
  • Quarterly key rotation on hginsights_v2 (the canonical v2 key used by all v2 tools in agent-service).
  • Replacing a leaked credential without webapp access.

Errors​

  • 400 invalid_request — missing or oversize value, missing integration_key.
  • 400 integration_disabled — catalog entry exists but is disabled.
  • 400 invalid_credentials — validator rejected the value.
  • 403 forbidden_admin_scope — caller's API key is not admin-scoped.
  • 404 integration_not_found — integration_key is not in the catalog.
  • 500 tool_setup_failed — credential saved, but a downstream sync (e.g., TrustRadius) failed. Safe to retry.

See also​