Verification & Operations

Connection test

The connection test runs the same three checks whether you trigger it from the UI, from the agent itself over MCP, or over REST:

1. Agent active — the agent's status is Active and it still has a live API token.
2. Environment keys — every authorized environment's sealed key unseals successfully, and can decrypt a sample variable when one exists.
3. Live resolve — a real secret is resolved through the exact same code path a genuine agent call uses (not a shortcut check), and discarded.

The result is persisted on the agent as last_tested_at and last_test_status (pass, fail, or untested), and returned as a checklist:

{
  "status": "pass",
  "checks": [
    { "name": "agent_active", "passed": true, "message": "The agent is active." },
    { "name": "agent_token", "passed": true, "message": "A valid API token exists for this agent." },
    { "name": "environment_key:production", "passed": true, "message": "The environment key unsealed successfully." },
    { "name": "live_resolve", "passed": true, "message": "A live secret resolved successfully through the resolution pipeline." }
  ]
}

Any single failed check fails the whole test. A failed environment_key:* check almost always means that environment's key was never provisioned from a browser that could decrypt it — revisit Getting Started → Unlock the vault.

Trigger it from:

• Web app: the Test connection button on the agent's page.
• MCP: call the test_connection tool (see MCP Integration).
• REST: POST /api/v1/agents/{agent}/test, authenticated with your own session token (this is a management endpoint, not one the agent calls on itself).

Audit trail

Every secret resolution — and every connection test's live-resolve check — is recorded internally, capturing:

• Which agent (and its name, preserved even if the agent is later deleted)
• Which user and organization it belongs to
• The action (secret_resolved for a genuine resolution, connection_tested for a diagnostic round-trip)
• The environment and variable name involved
• A timestamp

This gives you a durable record of exactly which secrets an agent has touched and when, independent of whether the agent still exists. A dedicated audit log viewer in the web application is on the roadmap — until it ships, this is the data that verification and any future reporting is built on.

Revoking an agent

From the agent's page, click Revoke. This immediately:

• Sets the agent's status to Revoked.
• Deletes its API token outright — there's nothing left to expire or clean up.

Any request using that token — MCP or REST — is rejected from that point on, regardless of which environments it was authorized for.

Deleting an agent entirely (instead of revoking it) does the same token cleanup, plus removes the agent and its environment authorizations. Its audit history is kept, with the agent's name preserved on those rows.

Rotating a credential

An agent's token can't be swapped in place — rotation means reactivating a revoked agent, which mints a brand-new token:

1. Revoke the agent (or it may already be revoked).
2. Click Reactivate. SecretStash mints a fresh token, shown exactly once, the same way the original token was shown when the agent was first created.
3. Update the agent's MCP or REST configuration with the new token. The old one no longer exists — there's no overlap window where both work.

If you want a zero-downtime rotation instead, create a new agent alongside the old one, authorize it identically, cut your agent's configuration over to the new token, and only then revoke the old agent.