>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588774. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Phase 6 site configuration currently uses browser automation against <code>/admin/config/system/site-settings</code> (NOT <code>/admin/config/system/site-information</code> &mdash; that path returns 403). The browser path is fragile: it depends on the browser session being warm, the WAF not intercepting the form POST, and selector names matching the current Drupal admin theme. The same failures that affect the menu-builder (2-01) can affect the site-configurator.</p> <p>The <code>site_settings:administer</code> OAuth scope (newly available in Acquia Source) was hypothesized to allow programmatic management of site name, logo, slogan, and front-page settings &mdash; reducing the site-configurator from a browser-automation flow to a ~5-line API script. With API access, <code>configure-site.sh</code> becomes a single OAuth POST instead of a browser form sequence.</p> <p>An empirical probe on 2026-05-01 against a live Acquia Source test instance confirmed the scope mints tokens but no JSON:API write endpoint is exposed. This issue is currently <strong>blocked-on-acquia-endpoint</strong>.</p> <p>Empirical probe results (live Acquia Source instance, 2026-05-01):</p> <ul> <li><code>site_settings:administer</code> scope minted an OAuth token (HTTP 200) &mdash; scope IS registered.</li> <li>All candidate endpoint paths returned HTTP 404: <ul> <li><code>/api/site_setting</code> &rarr; 404</li> <li><code>/api/site_setting/site_setting</code> &rarr; 404</li> <li><code>/api/config/site</code> &rarr; 404</li> <li><code>/api/system/system</code> &rarr; 404</li> <li><code>/api/site_settings</code> &rarr; 404</li> <li><code>/api/system/site</code> &rarr; 404</li> </ul> </li> <li>The full JSON:API discovery doc (<code>GET /api</code>) lists 20 entity types &mdash; none is a site-settings or system-config entity. No <code>config--system.site</code> or equivalent path is exposed.</li> </ul> <p>Conclusion: <code>site_settings:administer</code> grants a token but no endpoint is available on this release. The browser-automation path to <code>/admin/config/system/site-settings</code> remains the only write path for site name, slogan, logo, and front page.</p> <p><strong>Update 2026-05-11 (re-probe):</strong> Confirmed still blocked on this release. Re-probed with an expanded candidate list: <code>/api/site_setting</code>, <code>/api/site_settings</code>, <code>/api/system/site</code>, <code>/api/config/site</code>, <code>/jsonapi/config_pages</code>, <code>/jsonapi/config</code>, <code>/jsonapi/system_site</code>, <code>/jsonapi/contact_form</code>, <code>/jsonapi/block_content</code>, <code>/jsonapi/canvas_site_settings</code>, <code>/jsonapi/canvas_site_config</code>, <code>/jsonapi/site_config</code>, <code>/jsonapi/canvas_site_identity</code> &mdash; all 404. The full <code>/api</code> discovery doc on 2026-05-11 contains exactly 20 link rels: <code>menu_items--{footer,main,social-media}</code>, <code>page</code>, <code>file--file</code>, <code>media--{acquia_dam_*,document,image,remote_video,video}</code>, <code>taxonomy_term--{categories,tags}</code>, <code>node--{article,person}</code>, plus the <code>self</code> link. No site-settings entity in any form. Standard Drupal <code>/jsonapi</code> namespace also returns 404 &mdash; Acquia exposes only <code>/api/*</code>. Browser automation against <code>/admin/config/system/site-settings</code> remains the only write path. Re-probe on every new Acquia Source release.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Request an OAuth token with <code>scope=site_settings:administer</code> against a current Acquia Source instance.</li> <li>Confirm: HTTP 200, valid <code>access_token</code> in response.</li> <li>Probe each candidate path (<code>/api/site_setting</code>, <code>/api/system/site</code>, <code>/api/config/site</code>, etc.) with the token. Confirm: all return HTTP 404.</li> <li><code>GET /api</code> discovery doc &mdash; confirm no system-config entity is listed.</li> <li>Conclude: API endpoint is not shipped; the API-first replacement is currently blocked.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p><strong>Step 1 &mdash; Re-probe on each Acquia Source release.</strong> Add the <code>site_settings:administer</code> probes to the Phase 0.5 scope-availability preflight (1-08). When any candidate path first returns 200 with site-config data on a future release, this issue unblocks.</p> <p><strong>Step 2 &mdash; When endpoints land, write API-first <code>scripts/configure-site.mjs</code>:</strong></p> <pre>// scripts/configure-site.mjs &mdash; API-first site config (blocked until endpoints ship) import { readFileSync } from 'fs'; const plan = JSON.parse(readFileSync('docs/migration/plan.json', 'utf8')); const token = await getToken('site_settings:administer'); await fetch(`${SITE_URL}/jsonapi/config/system.site`, { method: 'PATCH', headers: { 'Content-Type': 'application/vnd.api+json', Authorization: `Bearer ${token}` }, body: JSON.stringify({ data: { type: 'config--system.site', attributes: { name: plan.site_name, slogan: plan.site_slogan ?? '', page: { front: plan.front_page ?? '/node/1' }, }, }, }), });</pre><p>Logo upload may be a separate step (media entity or file field on system.site config). Research the Drupal JSON:API endpoint for logo upload with <code>site_settings:administer</code> token when the base endpoint lands.</p> <p><strong>Step 3 &mdash; Update site-configurator agent (when unblocked):</strong></p> <pre>PRIMARY PATH (if site_settings:administer write confirmed by preflight): Run scripts/configure-site.mjs with OAuth token. No browser required. FALLBACK PATH (if site_settings:administer denied or endpoint missing): Use browser automation at /admin/config/system/site-settings (NOT /admin/config/system/site-information &mdash; 403 on that path).</pre><h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Re-run the scope/endpoint probe on each new Acquia Source release.</li> <li>When write endpoints land: implement <code>scripts/configure-site.mjs</code> per Step 2.</li> <li>When endpoints land: restructure <code>.claude/agents/site-configurator.md</code> to API-first primary, browser fallback.</li> <li>When endpoints land: confirm the exact JSON:API entity type (e.g., <code>config--system.site</code>) and document the PATCH payload in <code>gotchas.md</code>.</li> <li>Investigate logo upload separately &mdash; it may use a different scope or a media-upload endpoint.</li> <li>Until endpoints land: keep this issue tagged <code>blocked-on-acquia-endpoint</code>; update the empirical-results section after each re-probe.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>This issue consumes (does not introduce) existing endpoints: <code>POST /oauth/token</code> with <code>scope=site_settings:administer</code>, plus the eventual <code>PATCH /jsonapi/config/system.site</code> (or equivalent) when it lands. The endpoint surface is currently absent on the probed Acquia Source release.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New artifact (when unblocked): <code>scripts/configure-site.mjs</code>. New <code>gotchas.md</code> entry: confirmed <code>site_settings:administer</code> endpoint path and PATCH payload format.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-2-Determinism/06-NEW-8-site-settings-administer-api.md</code> (id: NEW-8)</li> <li>Empirical probe results: <code>RESEARCH-2026-04-28/99-final/SCOPE-PROBE-FINDINGS-2026-05-01.md</code> &sect; 7 ("NO endpoints exist for: site_settings, content_type, page_template, taxonomy_vocabulary, media_type")</li> <li>Probe script: <code>RESEARCH-2026-04-28/scripts/scope-probe.sh</code></li> <li>Scope reference: <code>RESEARCH-2026-04-28/99-final/SCOPE-REFERENCE-2026-05-01.md</code> &sect; "CRITICAL impact &mdash; site_settings:administer"</li> <li>Browser-path script design this would replace: 2-02 &sect; Recommendation Step 3 (<code>configure-site.sh</code>)</li> <li>Paired API-first issue: 2-05 (NEW-7, menu:administer)</li> <li>Preflight dependency: 1-08 (NEW-11)</li> <li>efi-ed vs freelygive-ai contrast (config endpoint paths): <code>RESEARCH-2026-04-28/05-freelygive-ai/patterns-vs-efi-ed.md</code></li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>What is the actual JSON:API endpoint Acquia Source plans to expose for <code>system.site</code> configuration? None of the candidate paths returned 200 on 2026-05-01.</li> <li>Does <code>site_settings:administer</code> cover logo upload (a file upload operation), or only text fields (site name, slogan, front page)? Logo is a file entity reference &mdash; it may require a separate scope or a media upload endpoint.</li> <li>Is the Drupal config entity type name <code>config--system.site</code>, or does Acquia Source use a different config entity? The exact type string affects the PATCH payload.</li> <li>Re-run the probe on each new Acquia Source release.</li> </ul>