Troubleshooting and safe handling

Start with the HTTP status, the endpoint, the intended workspace/environment and the token's non-secret ID. Keep bearer values, secret values and full exports out of bug reports.

Authentication and authorization

Symptom	Next step
401	Verify the credential is loaded in this process and has not expired or been revoked; create a replacement through an authorized human if needed
403	Check the exact module action, live actor role and grants; value comparison needs read plus values, and rollback needs edit plus values
404	Confirm the environment/name and token workspace; an inaccessible workspace can intentionally look absent
400 requiring workspace	A browser-session request needs the selected workspace ID; a token normally selects its own workspace
415	Send Content-Type: application/json, including {} for current-value reveal

Use GET /api/work/auth/token-self to inspect credential metadata. Do not debug by printing the Authorization header. A login-provider token is not a workspace automation token. A workspace slug is not a workspace ID.

If a token has Manage, that alone does not grant Read metadata or Read secret values. Selecting dev does not make its scopes specific to that environment.

Service or network failure

A 503 from a Secrets operation means the API could not reach its Secrets service. Ask the operator to check that service. GET /api/secrets/status instead reports available: false for service unavailability; its HTTP success does not mean the service is healthy.

A 501 can indicate a service version mismatch. A 502 can include a service-side rejection as well as an unexpected failure: read the sanitized error message before retrying.

For DNS, TLS or timeout problems, check connectivity from the affected machine. Do not disable TLS verification. An unauthenticated request to /api/secrets/workspace should be refused with 401; receiving that response demonstrates the authentication endpoint is reachable without using a credential. It does not prove an authenticated operation will succeed.

Do not start a replacement local store to fix remote connectivity. Remote clients use the authenticated HTTPS API.

A save or import partly worked

HTTP 200 on Save or Import can contain item-level errors. Inspect every result. A failed rename skips edits targeting the failed new name, while unrelated changes may already have applied. Refresh the environment and retry only the remaining intended changes.

After a timeout, inspect metadata before retrying a write. Creation with a note and renaming with edits can each use multiple underlying operations; a later failure does not prove earlier work was undone.

If a type change says to re-enter the value, it would weaken the display's redaction. Do not work around the refusal by exporting a whole environment. Review whether making that value visible to metadata readers is actually intended.

History or comparison looks surprising

History authors may be unknown on older records. replaced_by describes who replaced a previous version, not its original author. Restoring a version creates a new current version; older history can be unavailable due to retention settings.

A metadata comparison checks presence, types and display values. Two *** displays do not establish equal protected values. Actual value comparison requires value access and retrieves all selected environments' values.

Handle values safely

• Request one named value when the task needs one; export only when the whole environment is needed.
• Keep credentials in a credential manager and load them into the calling process only. Clear temporary environment variables afterward.
• Keep values out of prompts, logs, screenshots, issue reports, shell history and source control. Names and notes are metadata, so keep credentials out of those too.
• Treat clipboard entries, downloads and temporary files as copies of the secret. Restrict access and remove them when no longer needed.
• Cache-Control: no-store is a response directive, not an erasure guarantee for client memory, output or screenshots.
• Metadata display values can be plaintext: certificate, publishable and config are unmasked; connection strings are partly masked.

If a token leaks, revoke it and replace the affected client credential. If a stored value leaks, rotate or revoke it at the service that issued it and update AsyncFlux Secrets. API-token revocation cannot erase values already copied by a client.