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 β
| Permission | Permitted Actions | Denied Actions |
|---|---|---|
canRead | GET /api/vault, GET /api/notes, GET /api/keys, GET /api/attachments | Creating, editing, or deleting items |
canWrite | POST /api/vault, POST /api/vault/bulk-import, POST /api/notes, POST /api/keys, POST /api/attachments | Editing existing items or deleting items |
canEdit | PUT /api/vault/:id, PUT /api/notes/:id, PUT /api/keys/:id, PUT /api/attachments/:id | Deleting items |
canDelete | DELETE /api/vault/:id, DELETE /api/vault/bulk, DELETE /api/notes/:id, DELETE /api/keys/:id, DELETE /api/attachments/:id | Modifying settings or agent keys |