Authenticated widget settings and reviewed changes

get_guild_widget_settings returns one authenticated privacy-minimized widget-settings audit for a separately allowlisted guild. Set capabilities.widgetSettingsAudit: true and list every eligible guild in scopes.widgetSettingsGuildIds. This allowlist must be a subset of readScope.guildIds when the outer read allowlist exists. The equivalent discord://guilds/{guildId}/widget-settings resource applies the same scope and projection.

Every audit verifies the configured application and bot identities, exact guild and owner, connector membership, complete bounded roles, visible direct guild channels and their permission overwrites, effective MANAGE_GUILD, and the exact authenticated settings object. Optional widget_enabled and widget_channel_id fields on the guild object are used only as a contradiction-detecting cross-check when Discord supplies them. The selected channel is resolved by exact ID, and the audit reports whether it is a supported direct text, voice, announcement, Stage, forum, or media channel, whether @everyone can view it, whether @everyone can create invites there, and whether unknown permission bits prevent a complete decision. A selected channel omitted from Discord's HTTP inventory is unsafe and blocks a change rather than proving the guild has no other channels.

The connector never calls Discord's anonymous widget JSON or widget-image endpoints. Those routes can disclose public guild, channel, presence-oriented, and invite information that is unnecessary for authenticated administration. Results therefore omit channel names, member and presence data, invite codes and URLs, raw payloads, and unknown-field values. This privacy boundary also means API readback cannot verify the anonymous visitor experience, generated-invite behavior, or Private Profile state.

Changes have no immediate-call path. Set capabilities.widgetSettingsChanges: true in addition to audit scope. The strict request is one complete desired state containing the exact enabled boolean, one nullable channel ID, a bounded Discord audit-log reason, and a unique one-shot operation key. A null channel deliberately clears the configured invite target.

The independent capabilities.widgetPublicExposure: true gate is action-sensitive. A real write requires it when the desired widget remains or becomes enabled, or when a different non-null channel is selected even while disabled because that creates a latent public invite target. A no-op never requires it. A reviewed disable that retains the existing channel and a reviewed clear while disabled may proceed without it. Enabling the widget makes the Server Profile public outside the guild and may permit anonymous invite generation. Disabling the widget does not restore Private Profile, so a manual Server Settings change may still be required.

Planning requires authoritative current settings with no unknown fields, complete MANAGE_GUILD authority unless the connector is the exact guild owner, complete known permission bits, and one exact supported direct channel visible to @everyone when a channel is selected. CREATE_INSTANT_INVITE for @everyone is reported as exposure evidence but is not treated as a write permission requirement. Missing channels, categories or other unsupported targets, hidden channels, contradictory cross-checks, incomplete evidence, unknown permission bits, malformed state, or an uncertain same-guild predecessor fail closed.

1. Call get_guild_widget_settings to inspect authenticated state, identity and authority evidence, selected-channel exposure, public-profile implications, privacy omissions, and verification limits.
2. Call plan_guild_widget_settings_change with the exact complete desired state, Discord audit-log reason, and unique one-shot operation key.
3. Review the verified application and bot IDs, exact guild, current and desired states, enabled and channel diffs, complete permission and channel evidence, public-exposure authorization, privacy boundary, risks, warnings, operation-key hash, and keyed digest.
4. If the plan reports already-current, no confirmation, reservation, activity record, or Discord write is needed.
5. Call execute_guild_widget_settings_change with identical inputs plus the digest.
6. Approve the signed MCP confirmation only if every displayed field, exposure consequence, permission decision, audit reason, operation-key hash, and digest remains intended, then inspect the verification result and perform any recommended non-member or Private Profile follow-up manually.

The process-keyed HMAC digest binds the normalized complete request, verified identities, exact guild and owner, connector membership and roles, effective permissions, complete channel and overwrite inventory, authoritative authenticated current state, optional guild cross-check, desired state, diff, action-sensitive exposure authorization, privacy projection, verification boundary, risks, warnings, and one-shot key hash. A connector restart invalidates outstanding digests. The MCP adapter rebuilds the plan before approval, and the service rebuilds it immediately before mutation. Any identity, authority, permission, channel, overwrite, current-state, cross-check, enablement, target, audit-reason, exposure-policy, or operation-key drift invalidates the reviewed plan.

Execution atomically reserves the operation-key hash and appends a pending content-free activity record before one non-retried complete-state PATCH carrying the encoded Discord audit-log reason. The authenticated response must contain exact known fields and match a safe desired channel, and a second complete fresh evidence read verifies the controlled state. Exact response and readback agreement is completed; valid controlled-state drift is completed-with-drift; a definite Discord client refusal is failed; and transport failure, Discord server error, malformed success, failed response validation, failed readback, or failed receipt finalization is uncertain. Every reserved key remains spent, and the connector never retries, rolls back, or compensates automatically.

All widget-settings changes in one guild serialize inside one process. The production facade additionally acquires a durable exact guild widget-settings collection claim, so connector processes sharing the activity-state root exclude overlapping changes. An uncertain result retains that claim for operator review before another execution can replan, reserve, or write. Activity and operation records contain only the exact guild ID, plan digest, operation-key hash, timestamps, fixed verification and outcome values, activity ID, and sanitized error category. Enabled state, selected channel IDs, guild and channel names, permission evidence, exposure details, audit reasons, raw operation keys, raw payloads, and transport causes never enter durable records, diagnostics, or telemetry.

The optional privacy-safe Gateway feed may emit the existing content-free guild-updated event as a hint to perform another authenticated read. The connector keeps no widget cache and never treats a Gateway event as authoritative settings evidence. After enabling, review the Server Profile and widget from a fresh non-member context. After disabling, inspect Server Settings and restore Private Profile manually if needed. See Discord's guild widget settings endpoints and Server Profile visibility guidance.

Canonical source: docs/reference.md