3892e4dee1
1. Token Management API (closes production gap):
- GET /workspaces/:id/tokens — list tokens (prefix + metadata, never plaintext)
- POST /workspaces/:id/tokens — create new token (plaintext returned once)
- DELETE /workspaces/:id/tokens/:tokenId — revoke specific token
- Behind WorkspaceAuth middleware (need existing token to manage tokens)
- Tests skip gracefully when no DB available
2. MCP Server Setup:
- Fix .mcp.json to use npx @molecule-ai/mcp-server (was referencing
non-existent local ./mcp-server/dist/index.js)
- Add comprehensive tool→API mapping doc (87 tools across 15 categories)
3. External Agent Registration Guide:
- Step-by-step: create workspace, register, heartbeat, A2A messaging
- Python (Flask) and Node.js (Express) complete working examples
- Communication rules, lifecycle, security, troubleshooting
4. Token Management Guide:
- Bootstrap flow, rotation procedure, security properties
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
117 lines
3.4 KiB
Markdown
117 lines
3.4 KiB
Markdown
# Token Management API
|
|
|
|
Workspace bearer tokens authenticate agents and API clients against the Molecule AI platform. Each token is scoped to a single workspace — a token from workspace A cannot access workspace B.
|
|
|
|
## Endpoints
|
|
|
|
All endpoints are behind `WorkspaceAuth` middleware — you need an existing valid token to manage tokens for a workspace. The first token is issued during workspace registration (`POST /registry/register`).
|
|
|
|
### List Tokens
|
|
|
|
```
|
|
GET /workspaces/:id/tokens
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
Returns non-revoked tokens for the workspace. Only metadata is returned — never the plaintext or hash.
|
|
|
|
```json
|
|
{
|
|
"tokens": [
|
|
{
|
|
"id": "uuid-of-token-row",
|
|
"prefix": "abc12345",
|
|
"created_at": "2026-04-16T12:00:00Z",
|
|
"last_used_at": "2026-04-16T15:30:00Z"
|
|
}
|
|
],
|
|
"count": 1
|
|
}
|
|
```
|
|
|
|
### Create Token
|
|
|
|
```
|
|
POST /workspaces/:id/tokens
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
Mints a new token. The plaintext is returned **exactly once** — save it immediately.
|
|
|
|
```json
|
|
{
|
|
"auth_token": "dGhpcyBpcyBhIHRlc3QgdG9rZW4...",
|
|
"workspace_id": "ws-uuid",
|
|
"message": "Save this token now — it cannot be retrieved again."
|
|
}
|
|
```
|
|
|
|
### Revoke Token
|
|
|
|
```
|
|
DELETE /workspaces/:id/tokens/:tokenId
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
Revokes a specific token by its database ID (from the List response). The token is immediately invalidated.
|
|
|
|
```json
|
|
{
|
|
"status": "revoked"
|
|
}
|
|
```
|
|
|
|
Returns 404 if the token doesn't exist, belongs to a different workspace, or is already revoked.
|
|
|
|
## Token Lifecycle
|
|
|
|
```
|
|
Issue (register or POST /tokens)
|
|
→ Active (used via Authorization: Bearer)
|
|
→ Revoked (DELETE /tokens/:id or workspace deleted)
|
|
```
|
|
|
|
- Tokens have no expiration — they remain valid until explicitly revoked or the workspace is deleted
|
|
- On workspace deletion, all tokens are automatically revoked
|
|
- Multiple tokens can exist simultaneously per workspace (for rotation)
|
|
|
|
## Token Rotation
|
|
|
|
To rotate credentials without downtime:
|
|
|
|
1. **Create** a new token: `POST /workspaces/:id/tokens`
|
|
2. **Update** your agent to use the new token
|
|
3. **Verify** the new token works (check `last_used_at` in List)
|
|
4. **Revoke** the old token: `DELETE /workspaces/:id/tokens/:oldTokenId`
|
|
|
|
## Security Properties
|
|
|
|
- **256-bit entropy**: Tokens are 32 random bytes, base64url-encoded (43 characters)
|
|
- **Hash-only storage**: Only `sha256(token)` is stored in the database — plaintext is never persisted
|
|
- **Workspace-scoped**: Token from workspace A cannot authenticate as workspace B
|
|
- **One-time display**: Plaintext returned only at creation — not recoverable from the database
|
|
- **Prefix for identification**: First 8 characters stored for log correlation without revealing the token
|
|
|
|
## Bootstrap: Getting Your First Token
|
|
|
|
The first token is issued during workspace registration:
|
|
|
|
```bash
|
|
# 1. Create workspace
|
|
curl -X POST http://localhost:8080/workspaces \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"name": "My Agent", "tier": 2}'
|
|
|
|
# 2. Register (returns auth_token)
|
|
curl -X POST http://localhost:8080/registry/register \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"workspace_id": "<id>", "url": "http://...", "agent_card": {...}}'
|
|
# Response: {"auth_token": "...", ...}
|
|
```
|
|
|
|
For development, the test-token endpoint is also available (disabled in production):
|
|
```bash
|
|
curl http://localhost:8080/admin/workspaces/<id>/test-token
|
|
# Response: {"auth_token": "...", "workspace_id": "..."}
|
|
```
|