---
title: Troubleshooting and safe handling
description: Diagnose access and service failures without exposing credentials or secret values.
---

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.