shz-backend/.codex/skills/shz-pc-debug/references/authenticated-api.md

Protected API Calls in the Test Environment

Use this workflow only when needed

Use this workflow only when the user explicitly asks to call a protected API and identifies the test role, endpoint, and purpose. Default to test endpoints and a read-only request. Require separate explicit user approval for any protected request that creates, updates, deletes, submits, publishes, or otherwise changes business data.

Obtain and handle the test Token

1. Read test-environment.md and select only the configured test account and role needed for the request.
2. Locate the login request contract in project source or approved API documentation. Prefer source investigation over repeatedly opening Chrome DevTools.
3. Perform a direct test-login request and capture its short-lived Token only into a process-scoped shell variable or equivalent in-memory credential store. Suppress login-response output that could reveal the Token.
4. Use the Token only in the authorization header of the one or closely related user-requested test API calls. Do not request additional endpoints merely because the Token permits them.
5. Clear the variable or in-memory credential immediately after the calls complete or fail.

Never obtain a Token by reading browser cookies, local storage, session storage, or browser-exposed credentials. Never copy a Token from Chrome DevTools into another tool. Never print, log, persist, commit, screenshot, or report a Token or authorization header.

Choose the right tool

• Use Chrome DevTools for page interaction, DOM/UI failures, one representative request when the browser contract is unknown, and final visual verification.
• Use a narrow direct HTTP client for the explicitly requested protected API call after the endpoint and contract are known. This avoids the overhead of repeatedly driving Chrome DevTools.
• Do not use page JavaScript to make direct API requests or to access credentials.

Report safely

Report the test environment, selected role, endpoint path, HTTP method, status code, duration, and a redacted response summary. Omit the login payload, Token, authorization header, cookies, and personally identifiable fields not needed to establish the result.