Token Management

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.

These workspace bearer tokens are the narrowest of three credential tiers — sitting below org API keys and the control-plane admin token. The full model:

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

GET /workspaces/:id/tokens
Authorization: Bearer <token>

Returns non-revoked tokens. Only metadata is returned — never the plaintext or hash.

{
  "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.

{
  "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).

{
  "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:

# 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):

curl http://localhost:8080/admin/workspaces/<id>/test-token

Security properties