Auth Preflight Checklist

intent

run this checklist before any auth-dependent task: docs, troubleshooting, cron jobs, deploys, API integrations, or anything where the result depends on a token, service account, OAuth session, 1Password item, gateway model route, deploy key, or approval flag. the goal is simple: do not infer auth from configuration alone. prove the same runtime that will do the work can access the credential and complete the smallest safe live action. this prevents silent failures, scope mismatches, and wasted debugging time.

inputs

• active auth lane type: human OAuth, Codex subscription, OpenClaw gateway, raw API key, 1Password service account, deploy key, GitHub App, or provider token (string, required)
• runtime environment: interactive shell, LaunchAgent, cron, OpenClaw gateway, subagent, CI, VPS, container, or browser session (string, required)
• secret source reference: vault name, 1Password item ID, env var name, or gateway route (string, required)
• target resource: specific database, repo, branch, app, project, model route, webhook, or API endpoint (string, required)
• external connections (if applicable):
  • Notion: bot token or OAuth token (env var: NOTION_TOKEN or NOTION_API_KEY); scope: read database contents and metadata
  • GitHub: personal access token, GitHub App installation token, or deploy key (env var: GITHUB_TOKEN or GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY); scope: repo read, app installation access
  • Vercel: API token (env var: VERCEL_TOKEN); scope: project read, deployment read
  • Coolify: API token (env var: COOLIFY_API_TOKEN); scope: app/project read
  • OpenClaw/Codex: API key or gateway route (env var: OPENAI_API_KEY or Codex subscription via gateway); scope: model routing, inference
  • 1Password: service account token or Connect API token (env var: OP_SERVICE_ACCOUNT_TOKEN or ONEPASSWORD_CONNECT_TOKEN); scope: read vault item fields
• edge cases to consider:
  • auth token expiry or refresh window
  • rate limits on probe calls (GitHub API, Notion API, etc.)
  • network timeout or gateway unavailability
  • missing or empty result sets from read probes
  • token revocation or scope downgrade mid-task
  • env var shadowing (local override vs. inherited)
  • firewall or VPN restrictions on outbound probe calls

procedure

1. identify the active auth lane.

   • input: task description, config files, env setup, or ticket context
   • enumerate all possible credential sources: human OAuth session, Codex subscription token, OpenClaw gateway route, raw API key, 1Password service account, deploy key, GitHub App, or provider token.
   • output: single chosen lane (e.g. "GitHub personal access token via GITHUB_TOKEN env var")

2. document the runtime environment.

   • input: where the task will execute (shell, cron, CI, container, browser, etc.)
   • cross-check: does the credential lane match the runtime? (e.g. does launchd have access to the env var, does the container have the mounted secret, does the CI pipeline inject the token before this job step?)
   • output: confirmed runtime and confirmation that the auth lane is accessible from that runtime

3. verify secret source and runtime agreement.

   • input: expected vault name, item ID, env var name, or gateway route
   • check presence only: confirm the secret exists at that location; never print or log secret values
   • if the job runs under launchd, cron, container, or CI, verify the secret inside that exact environment or with an equivalent env capture (e.g. ssh into container && echo $MY_SECRET_NAME or launchctl getenv MY_SECRET_NAME)
   • output: confirmation that the secret is present and accessible from the target runtime

4. run the smallest live probe.

   • input: target resource type and location
   • execute one minimal read-only action to prove auth works:
     • Notion: retrieve bot/user info or list target database with curl -H "Authorization: Bearer $NOTION_TOKEN" https://api.notion.com/v1/users/me or equivalent client call
     • GitHub: read repo metadata or list app installation access with gh api repos/{owner}/{repo} or curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/repos/{owner}/{repo}
     • Vercel/Coolify: read project/app metadata before deploy with provider CLI or API read call
     • OpenClaw/Codex: run a tiny gateway model smoke test (e.g. single token completion with minimal context)
     • 1Password: read the exact item field with bounded retry (max 3 retries, 2s backoff) using op item get <item-id> --vault <vault-name> --fields label=<field-name>
   • output: HTTP 200, valid JSON response, or command exit code 0 (proof that the auth path works)

5. check scopes and target access.

   • input: auth token/credential and the specific resource it needs to touch
   • confirm the token can access the specific database, repo, branch, app, project, model route, or webhook target
   • do not assume: token exists does not guarantee scope or resource access
   • if applicable, check token scope claim (e.g. gh api user for GitHub, or JWT decode for OAuth tokens)
   • output: list of verified scopes and confirmed access to target resource

6. fail with a useful blocker if any step fails.

   • input: failure point (missing secret, 401 auth error, 403 scope error, probe timeout, etc.)
   • include in blocker: missing auth lane, expected secret reference, runtime, exact probe command used, HTTP response class (401/403/5xx), and next owner/action (e.g. "ask DevOps to rotate the Codex token" or "enable read:repo scope on this GitHub App")
   • do not continue into writes, deploys, or destructive actions after 401/403/missing scope unless the task explicitly asks for forensic collection only
   • output: blockers logged or raised as structured error with all details

decision points

• if auth lane is human OAuth: verify the session is active (check session cookie expiry, last activity timestamp); if expired, re-authenticate before probe
• if auth lane is env var or deploy key: confirm presence and accessibility from the target runtime; if not found, check for typos, scoping issues (global vs. job-level), or missing secret injection in CI/container config
• if probe returns 401 (unauthenticated): secret is either missing, malformed, or revoked; escalate to credential owner or rotation process
• if probe returns 403 (forbidden): secret is valid but lacks scope or resource access; check token scope claim and resource permissions; escalate to access control owner
• if probe times out or returns 5xx (server error): gateway or provider is down or unreachable; retry probe once after 10s backoff; if still failing, check outbound firewall rules and provider status page; do not assume auth is broken
• if target runtime is cron/launchd/container and secret is missing at runtime: verify env injection step in job config, mount path for secrets, or 1Password/vault integration setup
• if OpenClaw raw API key is missing but Codex-backed gateway route works: prefer gateway routing; raw API key absence is not a blocker if the routed path is proven
• if result set is empty (e.g. database list returns zero items): auth succeeded but user has no access to any resource; confirm expected resource exists and user has grant; this is not an auth failure but an access/permission issue

output contract

on success, produce:

• preflight report (plaintext, markdown, or JSON): single confirmed auth lane, runtime environment, secret reference, probe command used, probe response (status code, response time, no secret values), list of verified scopes, and confirmation of target resource access
• file location: log to task ticket, CI job log, or preflight-{timestamp}.txt in working directory
• format: human-readable checklist with pass/fail status for each step, or JSON object with keys: auth_lane, runtime, secret_reference, probe_command, probe_status, scopes_verified, target_resource_access, timestamp

on failure, produce:

• blocker report (required): structured error with keys: failure_point (which step failed), auth_lane (what was attempted), secret_reference (where it was looked for), runtime (where it was checked), probe_command (exact command run), error_code (401, 403, timeout, missing, etc.), error_message (full text), next_action (who to contact, what to do), timestamp

outcome signal

you know the preflight passed when:

• preflight command ran in the same runtime lane and returned 200/success (no 401, 403, or timeout)
• live action (write, deploy, API call) succeeded and produced the expected artifact or log entry
• blocker is recorded with exact missing credential, scope, approval, or access level, and next action is assigned

you know it failed when:

• probe returned 401 (auth invalid) or 403 (auth valid but insufficient scope/access)
• secret is not present at the expected reference in the target runtime
• probe timed out or returned 5xx (provider/gateway issue, but still a blocker for your task)
• no next action or owner is identified for the blocker

do not proceed to writes, deploys, or sensitive operations until all preflight steps pass or explicit forensic-collection-only mode is declared.