---
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 |
