Personal API key wk_: your MCP identity—not the team's admin password
You find it in the team repo: .cursor/mcp.json with a Bearer token mapped to an admin user. Every developer—and every AI prompt—connects to production with admin superpowers. A contractor offboards? Token still live. Audit asks "Who called finance_summary?" Answer: "Shared admin."
WKFGo's personal API key wk_ fixes that anti-pattern: each user mints their own key in Settings → Integrations → Connect your AI IDE, their FeatureAccess applies, and revoke is per person—not org-wide panic.
Browser JWT sessions are separate—MCP clients need a static header token; wk_ is designed for that long-lived IDE and automation use case.
Symptoms and cost of shared tokens
| Symptom | Cost |
|---|---|
| One admin key in team wiki | Permission inflation for every developer |
| Token in git history | Blast radius across the org |
| No attribution on tool calls | Audit and compliance gaps |
| Contractor leaves; key stays live | Confidential task and finance exposure |
| Forbidden response → switch to admin key | Security culture collapses |
The cost is not theoretical. A leaked wk_ with admin scope exposes every project, finance row, and document the org stores in WKFGo—the same PostgreSQL backend that powers /dashboard and /reports.
Six-step framework: issue, configure, and rotate keys
Step 1: Create in WKFGo per person
Settings → Integrations → Connect your AI IDE. Label clearly: "Ali MacBook Cursor" or "Sara Claude Desktop." Service accounts get their own labels: "ci-release-bot-readonly."
Step 2: Store securely—never in git
Password manager or secret store. Verify .cursor/mcp.json and similar configs are in .gitignore. Pre-commit secret scanning catches accidents before push.
Step 3: Configure MCP client
"Authorization": "Bearer wk_xxxxxxxx"
Exact server setup documented at /api-docs. Claude Desktop and Cursor use the same Authorization header pattern.
Step 4: Smoke-test permissions
Call finance_summary—if forbidden unexpectedly, check FeatureAccess assignments. If forbidden correctly for a developer role—least privilege works. Do not escalate to admin token.
Step 5: Define least-privilege tool sets
Typical developer MCP allow: list_tasks, get_task, update_status, search_docs, get_wiki_page, my_day, start_work, end_work. Deny by default: finance_summary, admin routes, delete operations. Change the role when access is legitimately needed.
Step 6: Rotation and offboarding
Rotate every 90 days or immediately after suspected leak. Revoke old key before issuing new. Contractor last-day checklist: revoke wk_ before badge return—same priority as laptop collection.
Permission mapping: wk_ equals web app
| User role | MCP experience |
|---|---|
| Developer on project A | Tasks and wiki for project A only |
| PM multi-project | Assigned projects per FeatureAccess |
| Read-only contractor | Read tools only; writes blocked |
| Admin | Broader access—still a personal key for attribution |
Every tool call passes through auth.ResolveUserID plus FeatureAccess middleware—the same stack as REST API routes in backend/routes.json.
Anti-patterns
- One
wk_in team wiki "for everyone" - Committing keys in screenshot tutorials or Slack threads
- Admin JWT in long-lived automation scripts instead of scoped service key
- Skipping revoke on offboarding checklists
- Sharing one key between Cursor and production CI—use two keys with different scopes
WKFGo auth stack (honest map)
- Browser login: HS256 JWT, 7-day TTL, stored in localStorage
- MCP / automation: personal API key
wk_… - Legacy numeric id bearer: only with
AUTH_LEGACY_TOKENS—off in production - Demo mode: demo user writes blocked on frontend and backend
- Every sensitive MCP tool: respects feature_key permissions like the web UI
Incident response: leaked key
- Immediate revoke in WKFGo settings
- Audit tool calls if available—attribution is why personal keys matter
- Issue new key per affected user only
- Retro: how it reached git or wiki
- Add or enforce pre-commit secret scan
Per-user revoke is the advantage—not rotating one shared token and hoping nobody copied it.
FAQ — personal wk_ keys
JWT vs wk_—when to use which?
JWT for web sessions in the browser; wk_ long-lived for MCP clients (Cursor, Claude Desktop) and automation bots.
Multiple keys per user?
Yes—one laptop, one CI bot with least privilege. Label each for readable audit trails.
Instant revoke?
Settings → Integrations—old calls fail immediately after revoke.
What about 2FA?
Follow your org identity policy—still protect keys like passwords; never paste in chat.
Permission discipline across UI, chatbot, and MCP
WKFGo resolves identity through JWT or personal wk_ keys and applies FeatureAccess on every tool call. Test with a contractor account before org-wide rollout. Forbidden responses mean permissions work—do not bypass with shared admin tokens.
Next step
Audit your team repo for shared tokens today. Issue personal wk_ keys. Run one permission smoke test. Add revoke to your offboarding checklist before the next contractor ends.