PAT rotation

WHY ROTATE PATs:
  Limit exposure if leaked
  Compliance requirement (typically quarterly)
  User left team / changed role
  Security incident
  Periodic hygiene (industry best practice for bearer tokens)

RECOMMENDED:
  Quarterly rotation (every 90 days): most common
  Immediate rotation on suspected leak
  Rotation when a user's role changes (your runbook, not automatic)

TRACKED in ZopNight UI (Settings → API & MCP):
  Each token's expiry date
  On the expiry date the token stops working (401)

SAFE ROTATION (no disruption):

  1. Generate new PAT
     ZopNight → Settings → API & MCP → Create Token
     Same orgs and write capabilities as before; new name

  2. Copy the new PAT (shown only once)

  3. Update the client's config (its Authorization header,
     or the secret store it reads from)
     Replace old PAT value with new

  4. Restart your AI tool (Claude Desktop, Cursor, etc.)
     Loads the new PAT

  5. Verify new PAT works
     Test query: "Who am I in ZopNight?"
     Should return your user (auth working)

  6. Revoke the OLD PAT
     ZopNight → Settings → API & MCP → delete the old token
     This is the moment the old PAT becomes invalid

5-minute process; done correctly, no disruption.

OPTION A: ZopNight API direct
  POST /auth/pat/{id}/rotate
  Body: { userEmail: "...", expiresIn: "90d" }
        (expiresIn is optional; leave it out to keep the expiry)
  Returns: the new secret (shown once); same token id
  The old secret is invalid the moment the call returns, so
  write the new one to your secret store in the same step

OPTION B: Secret manager integration
  1Password CLI rotates and re-syncs
  HashiCorp Vault rotates on schedule
  AWS Secrets Manager rotation lambda
  Each can call ZopNight API + update its store atomically

OPTION C: CI/CD orchestration
  Github Actions / Jenkins runs rotation script quarterly
  Script: generate new PAT → update secrets store → notify users

PROBLEM: rotate PAT while the agent has an active session

WHAT HAPPENS WITHOUT COORDINATION:
  Agent has old PAT in process memory
  You revoke old PAT
  Agent's next call returns 401 Unauthorized
  Agent breaks until restarted with new PAT

THE SAFE PATTERN:
  1. Generate new PAT
  2. Update client config (or its secret store) with new value
  3. Restart client (which reloads PAT)
  4. Verify new PAT works (test query)
  5. ONLY NOW revoke old PAT

If you skip step 4: agent breaks if new PAT is bad
If you skip step 5: old PAT stays valid (bad if leaked)

ENGINEER uses MCP from multiple devices:
  Cursor on laptop
  Claude Code on desktop workstation
  Claude Desktop on personal Mac (if BYOD allowed)

RECOMMENDED: one PAT per device

WHY:
  If a device is lost (e.g., laptop stolen), revoke that
  device's PAT; other devices keep working.

  If using one PAT across devices, losing one device requires
  revoking the shared PAT: interrupts work on the other devices.

NAMING convention:
  pat-laptop-2026-Q2   (or descriptive: "MBP-2026-Q2")
  pat-workstation-2026-Q2
  pat-personal-mac-2026-Q2

RESPONSE PROCEDURE:

  T+0     Engineer reports device lost / stolen
  T+5min  Open ZopNight → Settings → API & MCP
  T+5min  Identify PATs tied to lost device (by name)
  T+6min  Revoke immediately

  Other devices continue working (different PATs)
  Issue new PAT for replacement device when available

LATENCY:
  PAT revocation effective within 60 seconds
  AI tools on the lost device receive 401 on next call
  No way for the lost device to continue using the revoked PAT

SCENARIO 1: PAT pushed to public Git
  Action: revoke immediately; rotate; audit recent usage
  Forensics: check audit log for unfamiliar usage from the
             time of push to revocation

SCENARIO 2: PAT in old chat / Slack message
  Action: rotate when discovered; verify chat is purged
  Mitigation: secrets scanning on chat archives going forward

SCENARIO 3: Suspected insider misuse
  Action: revoke; investigate via audit log; report per
          security incident process
  Forensics: full audit log review for the user's recent activity

SCENARIO 4: Engineer leaves the company
  Action: revoke all their PATs (HR-triggered process)
  Verify: zero MCP calls from those PATs after revocation

SCENARIO 5: User account compromised
  Action: revoke ALL PATs for that user
  Investigate via audit log
  Reset user's password / re-authenticate SSO
  Investigate downstream actions taken

BAD NAMES (avoid):
  "test"
  "for stuff"
  "delete me"
  "" (empty)

GOOD NAMES:
  "Claude Code on jane-mbp 2026-Q2"
  "Cursor on dev-vm prod-account 2026-Q2"
  "CI cron audit-export 2026-Q2"
  "Datadog integration"
  "Notion integration via MCP-Notion 2026-Q2"

WHY: makes rotation easier ("rotate all jane-mbp PATs")
     Makes incident response easier ("revoke every token on
     jane-mbp")
     (Audit rows record the user, not which token, so a
     good name helps in Settings rather than in the audit log)

ZopNight has no org-wide PAT policy. Each token's limits are
chosen when it is minted:
  Name (the only label; there is no separate description field)
  Orgs it may act in
  Expiry
  Permissions (never more than its owner's)

Not in the product, so run them yourself:
  Maximum token age and rotation cadence → your runbook
  Expiry reminders → calendar or secret-manager alerts
  Approval for new tokens → your access-request process

WEEK 1 OF QUARTER (e.g., week of Jan 1, Apr 1, Jul 1, Oct 1):
  List PATs older than 60 days (ZopNight UI / API)
  Notify users via email: "your PAT XYZ expires in 30 days"
  Provide 1-week window for self-rotation
  Provide updated rotation runbook link

WEEK 2:
  Generate fresh PATs for users who didn't self-rotate
  Block usage of stale PATs (or escalate to user's manager)
  Update SIEM rules if needed

WEEK 3:
  Audit: zero PATs >90 days old? Verify.
  File quarterly compliance report
  Update org's runbook based on lessons learned

PAT generation: free
PAT rotation: free
PAT storage: free (metadata only)
Audit log entries: per ZopNight's pricing
LLM tokens: paid by AI tool, not ZopNight

So rotation has no infra cost: only ops effort.

DAY 1 (Quarter start):
  Runbook reminder: "Your PAT 'Claude Code on jane-mbp 2026-Q1'
  expires in 14 days. Plan to rotate this week."

DAY 2 (Jane responds):
  Jane opens ZopNight → Settings → API & MCP
  Clicks "Create Token" → "Claude Code on jane-mbp 2026-Q2"
  Same orgs and write capabilities; new name with the new quarter
  Generated: zn_pat_b3c5d7... (copies immediately)

  Re-adds the server in Claude Code with the new token:
    claude mcp remove zopnight
    claude mcp add --transport http zopnight <server-url> \
      --header "Authorization: Bearer zn_pat_b3c5d7..."

  Restarts Claude Code

  Verifies new PAT works:
    > /mcp
    ✓ zopnight: connected
    > "Who am I?"
    ✓ "jane@platform in Acme Corp"

  Revokes old PAT in ZopNight UI

  Records the rotation in the team's runbook log
  (PAT create, rotate and delete are not written to the
   org audit log)

ELAPSED: 5 minutes
DISRUPTION: 30 seconds while Claude Code restarts

TOTAL PATs you have:    _____

OLDEST PAT:
  Age:           _____ days
  Name:          __________
  Action needed: rotate / fine

PATs with vague names (replace):
  __________
  __________

PATs >75 days old (rotate this week):
  __________
  __________

ROTATION PLAN:
  □ Self-rotate this week
  □ Document in team wiki
  □ Set calendar reminder for next quarter

SECRETS-MANAGER integration:
  □ Yes (which: __________)
  □ No (consider automating quarterly rotation)