4f5bdc3f79
New pages: - external-agents.mdx — step-by-step remote agent registration guide with Python (Flask) and Node.js (Express) working examples - tokens.mdx — create, list, revoke workspace bearer tokens - mcp-server.mdx — 87-tool reference with API route mapping Framework upgrade (fumadocs v15.8 had a build crash "a.map is not a function" in DocsLayout page tree formatter — unfixable without upgrade): - fumadocs-core/ui: 15.8 → 16.7 - fumadocs-mdx: 11.10 → 14.3 - next: 15.5 → 16.2 - react/react-dom: 19.0 → 19.2 Migration: RootProvider import path, source import path, search route stubbed (full-text search TBD after fumadocs v16 search API stabilizes). Build: 19/19 static pages generated successfully. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
116 lines
2.9 KiB
Plaintext
116 lines
2.9 KiB
Plaintext
---
|
|
title: Token Management
|
|
description: Create, list, and revoke workspace bearer tokens for API authentication.
|
|
---
|
|
|
|
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. The first token is issued during workspace
|
|
registration (`POST /registry/register`).
|
|
|
|
### List tokens
|
|
|
|
```bash
|
|
GET /workspaces/:id/tokens
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
Returns non-revoked tokens. 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
DELETE /workspaces/:id/tokens/:tokenId
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
Revokes a specific token by its database ID (from the List response).
|
|
|
|
```json
|
|
{
|
|
"status": "revoked"
|
|
}
|
|
```
|
|
|
|
Returns 404 if the token doesn't exist, belongs to a different workspace, or
|
|
is already revoked.
|
|
|
|
## 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`
|
|
|
|
## 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": {...}}'
|
|
```
|
|
|
|
For local development, the test-token endpoint is also available (disabled in production):
|
|
|
|
```bash
|
|
curl http://localhost:8080/admin/workspaces/<id>/test-token
|
|
```
|
|
|
|
## Security properties
|
|
|
|
| Property | Detail |
|
|
|---|---|
|
|
| Entropy | 256-bit (32 random bytes, base64url-encoded) |
|
|
| Storage | sha256 hash only — plaintext never persisted |
|
|
| Scope | Per-workspace — token A cannot auth workspace B |
|
|
| Display | Shown once at creation, not recoverable |
|
|
| Prefix | First 8 characters stored for log correlation |
|
|
| Expiration | None — tokens are permanent until revoked |
|
|
| Auto-revoke | All tokens revoked when workspace is deleted |
|