Skip to main content

🔐 BYOK Keys

Bring your own Lighthouse key so uploads bill your plan: save it, check it, delete it. Mirrored as three MCP tools for agents.

Why BYOK?​

Without a saved key the backend bills the shared server key or fails uploads. Saving your own lh_... key isolates billing per user and unlocks the full MCP tool surface (no key = key-only mode: only the three key tools work).

Prerequisites​

  • A backend URL as API (whoever hosts it gave you this).
  • A session JWT as $JWT (paste the dashboard session token, or reuse the cloud-sync memory-login token). Dev alternative: MCP_BEARER_TOKEN.
  • A Lighthouse API key from the Files App (API Keys section).

Step 1 - Save the key (PUT /v1/keys)​

curl -X PUT $API/v1/keys \
  -H "authorization: Bearer $JWT" \
  -H "content-type: application/json" \
  -d '{"lighthouseKey":"lh_..."}'
# { "ok": true, "last4": "abcd", "userId": "clerk:<sub>" }  (userId only for JWT callers)
# 400 { "ok": false, "error": "Body must be { \"lighthouseKey\": \"lh_...\" }" }

Keys shorter than 10 chars are rejected. Saving again overwrites.

Agent equivalent (key-only mode): memory_api_key_save({ lighthouseKey }) — only last4 is ever returned. NOTE: the key passes through chat history — prefer the dashboard field on shared machines.

Step 2 - Check what is active (GET /v1/keys/status)​

curl $API/v1/keys/status -H "authorization: Bearer $JWT"
# { "ok": true, "saved": true, "last4": "abcd", "updatedAt": "…" }
# { "ok": true, "saved": false, "last4": "server", "updatedAt": null }  # shared fallback
# { "ok": true, "saved": false, "last4": null, "updatedAt": null }      # nothing available

last4: 'server' means no personal key is saved but the shared server key keeps uploads working. When nothing is available, uploads fail until you save a key.

Agent equivalent: memory_api_key_status.

Step 3 - Delete the key (DELETE /v1/keys)​

curl -X DELETE $API/v1/keys -H "authorization: Bearer $JWT"
# { "ok": true, "removed": true }

removed: false when nothing was saved. Future uploads fall back to the server key or fail until you save again.

Agent equivalent: memory_api_key_delete.

Storage​

Keys are stored encrypted and only last4 is ever returned. If saves fail with a generate-and-restart message, the host needs to configure the backend — retry after they confirm it.

Troubleshooting​

SymptomFix
Save fails with a generate-and-restart messageThe host needs to configure the backend — ask them, then retry.
last4: 'server' but you saved a keyRe-PUT the key — saving overwrites, status should flip to saved: true.
Agent only sees three key toolsNo BYOK key for that user — save one, then the full surface appears.
401 on /v1/keysBad / expired token — get a fresh session token from the dashboard.

Next steps​