Agent Check — Secret Server Token Validation

Use this skill at the start of any workflow that requires Secret Server access. It validates the current token and surfaces the result so you can decide whether to proceed or prompt the user to re-authenticate.

When to use

• Before any ss-cli get, ss-cli run, ss-cli refresh-env, or other secret access
• In automated pipelines to fail fast before attempting secret operations
• When the user asks you to fetch or use a secret

How to check the token

Run the token status check and parse the JSON response:

ss-cli token-status --json

Response fields:

Field	Description
valid	true if token is usable, false if expired or missing
source	"file" (from ss-cli login), "session" (SS_TOKEN env var), or "none"
minutesLeft	Remaining minutes (file-based only; null for session tokens)
expiresAt	ISO timestamp of expiry (file-based only; null for session tokens)

Token lifetime is organization-specific. Do not assume a fixed expiry window. Always check minutesLeft and expiresAt from the actual response.

Decision logic

token-status --json
  → valid: true   → proceed with ss-cli commands
  → valid: false  → stop. Tell the user: "Secret Server token is expired or missing. Please run: ss-cli login"

If minutesLeft is less than 5 and the workflow will take time, warn the user before starting so they can renew the token.

Script

Run the provided script for a shell-friendly gate that exits 0 (valid) or 1 (invalid):

./skills/agent-check/scripts/agent-check.sh || exit 1

Example agent workflow

# 1. Check token
TOKEN_JSON=$(ss-cli token-status --json)
# Parse valid field — if false, stop and tell the user to run: ss-cli login

# 2. Fetch a secret
ss-cli get 21909 --format json

# 3. Use the result

Security notes

• Never store secret values in files. Prefer ss-cli run (injects secrets as env vars into a subprocess) or ss-cli resolve (stdout-only).
• If source is "session", the token is in-memory only (from ss-cli session). It cannot be shared across terminals and vanishes when the shell exits.
• For cross-process agent access, source must be "file" (from ss-cli login).