Skip to content

LobsterKeys (lb-) Lifecycle ​

LobsterKeys are sovereign API keys created by human vault owners and provided to autonomous AI agents.


πŸ”‘ Key Format Specification ​

text
lb-a9f8c4e2b0d1e3f5a7c9fqBMX8juFQ1cnyJU5grCNY9kvGR2dozKV6hsDOZalwHS
└── Prefix (3 chars)
    └─────────────────── 256-bit Random Base62 Entropy (64 chars) β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Total Length: 67 characters.


πŸ”’ Step 1: Hashing the Key (Client / Agent Side) ​

The agent MUST NEVER send the raw lb- key over HTTP. The agent computes its SHA-256 hash first:

typescript
import crypto from 'node:crypto';

export function hashLobsterKey(lbKey: string): string {
  return crypto.createHash('sha256').update(lbKey).digest('hex');
}
python
import hashlib

def hash_lobster_key(lb_key: str) -> str:
    return hashlib.sha256(lb_key.encode('utf-8')).hexdigest()
bash
echo -n "lb-your-lobster-key-here" | sha256sum | awk '{print $1}'

🎟️ Step 2: Exchanging for an API Bearer Token ​

The agent calls POST /api/auth/token:

http
POST /api/auth/token
Content-Type: application/json

{
  "type": "agent",
  "keyHash": "a1b2c3d4e5f6..."
}

Response (200 OK): ​

json
{
  "success": true,
  "data": {
    "token": "api-9f8e7d6c5b4a3...",
    "expiresAt": "2026-08-28T21:00:00.000Z",
    "permissions": {
      "canRead": true,
      "canWrite": true,
      "canEdit": false,
      "canDelete": false
    }
  }
}

πŸ›‘οΈ Granular Permissions Matrix ​

PermissionPermitted ActionsDenied Actions
canReadGET /api/vault, GET /api/notes, GET /api/keys, GET /api/attachmentsCreating, editing, or deleting items
canWritePOST /api/vault, POST /api/vault/bulk-import, POST /api/notes, POST /api/keys, POST /api/attachmentsEditing existing items or deleting items
canEditPUT /api/vault/:id, PUT /api/notes/:id, PUT /api/keys/:id, PUT /api/attachments/:idDeleting items
canDeleteDELETE /api/vault/:id, DELETE /api/vault/bulk, DELETE /api/notes/:id, DELETE /api/keys/:id, DELETE /api/attachments/:idModifying settings or agent keys

Sovereign Zero-Knowledge Secrets Vault. Released under AGPL-3.0. β€’ Privacy Policy