RCA-2026-03-27-002: Claude Code Credential Vault Architecture

Executive Summary

Claude Code sessions failed with "Invalid API key" after implementing vault-based credential isolation. Root cause: symlink pointed to wrong file (credentials.json instead of .credentials.json). Claude Code stores OAuth tokens in .credentials.json (dot-prefixed hidden file), not the settings file. Resolution: create symlink for .credentials.json to vault, enabling proper credential isolation with gcvault mount/unmount cycle.

Timeline

Time Event

2026-03-25 19:17

Initial symlink created: ~/.claude/credentials.json → vault/credentials.json

2026-03-27 ~09:00

Discovered Claude still worked with vault unmounted (unexpected)

2026-03-27 09:02

Identified .credentials.json (local file) as auth token source

2026-03-27 09:03

Deleted .credentials.json to enforce vault isolation

2026-03-27 09:04

New Claude sessions fail: "Invalid API key"

2026-03-27 09:04

Re-login via /login in working session

2026-03-27 09:05

Created correct symlink: ~/.claude/.credentials.json → vault/.credentials.json

2026-03-27 09:06

Verified mount/unmount cycle works correctly

Problem Statement

Symptoms

  • Claude Code worked when credentials vault was unmounted (defeating purpose of vault isolation)

  • After deleting local credential file, Claude failed with "Invalid API key"

  • /login command created new local file instead of using symlinked vault file

Expected Behavior

  • Claude Code should fail when credentials vault is unmounted

  • Claude Code should work when credentials vault is mounted

  • OAuth tokens should be stored in vault, not locally

Actual Behavior

  • Claude Code used local .credentials.json fallback file

  • Symlink to credentials.json only handled settings, not auth tokens

Metadata

Field Value

RCA ID

RCA-2026-03-27-002

Author

Evan Rosado

Date Created

2026-03-27

Status

Final