feat(tokens): permanently delete agent tokens to free the name for reuse (#820) (#821)

Revoking an agent token is a soft delete: the record is kept so the token
name stays reserved, which blocks creating a new token with the same name
(issue #820). This adds a permanent delete that removes the token record and
its name->hash mapping, freeing the name for reuse.

- storage: DeleteAgentToken(name) removes both the agent_tokens record and the
  agent_token_names mapping in one tx.
- REST: DELETE /api/v1/tokens/{name}/permanent (distinct from the existing
  revoke DELETE /api/v1/tokens/{name}). Admin-only, 204/404.
- server edition: parallel DELETE /api/v1/user/tokens/{name}/permanent, scoped
  to the authenticated user.
- CLI: `mcpproxy token delete <name>` (aliases: rm, remove).
- Web UI: a Delete button on revoked/expired tokens (active tokens must be
  revoked first) with a confirm dialog.
- docs + agent-tokens API contract updated.

Tests: storage/API delete + name-reuse-after-delete, CLI subcommand wiring.

Author: Dumbris

cmd/mcpproxy/token_cmd.go

@@ -49,6 +49,7 @@ Examples:
 	tokenCmd.AddCommand(newTokenListCmd())
 	tokenCmd.AddCommand(newTokenShowCmd())
 	tokenCmd.AddCommand(newTokenRevokeCmd())
+	tokenCmd.AddCommand(newTokenDeleteCmd())
 	tokenCmd.AddCommand(newTokenRegenerateCmd())
 
 	return tokenCmd
@@ -395,6 +396,54 @@ func runTokenRevoke(_ *cobra.Command, args []string) error {
 	return nil
 }
 
+func newTokenDeleteCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     "delete <name>",
+		Aliases: []string{"rm", "remove"},
+		Short:   "Permanently delete an agent token",
+		Long: `Permanently delete an agent token, removing it entirely and freeing its
+name for reuse. Unlike revoke (a soft delete that keeps the record so the name
+stays reserved), delete removes the token completely.
+
+Examples:
+  mcpproxy token delete deploy-bot`,
+		Args: cobra.ExactArgs(1),
+		RunE: runTokenDelete,
+	}
+}
+
+func runTokenDelete(_ *cobra.Command, args []string) error {
+	client, _, err := newTokenCLIClient()
+	if err != nil {
+		return err
+	}
+
+	name := args[0]
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	resp, err := client.DoRaw(ctx, http.MethodDelete, "/api/v1/tokens/"+name+"/permanent", nil)
+	if err != nil {
+		return fmt.Errorf("failed to delete token: %w", err)
+	}
+	defer resp.Body.Close()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("failed to read response: %w", err)
+	}
+
+	if resp.StatusCode == http.StatusNotFound {
+		return fmt.Errorf("token %q not found", name)
+	}
+	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusNoContent {
+		return parseAPIError(respBody, resp.StatusCode, "delete token")
+	}
+
+	fmt.Printf("Token %q has been permanently deleted.\n", name)
+	return nil
+}
+
 func newTokenRegenerateCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "regenerate <name>",

cmd/mcpproxy/token_cmd_test.go

@@ -23,9 +23,34 @@ func TestGetTokenCommand(t *testing.T) {
 	assert.True(t, names["list"], "should have 'list' subcommand")
 	assert.True(t, names["show"], "should have 'show' subcommand")
 	assert.True(t, names["revoke"], "should have 'revoke' subcommand")
+	assert.True(t, names["delete"], "should have 'delete' subcommand")
 	assert.True(t, names["regenerate"], "should have 'regenerate' subcommand")
 }
 
+func TestGetTokenCommand_IncludesDelete(t *testing.T) {
+	cmd := GetTokenCommand()
+
+	// Find the delete subcommand
+	var deleteCmd *cobra.Command
+	for _, sub := range cmd.Commands() {
+		if sub.Name() == "delete" {
+			deleteCmd = sub
+			break
+		}
+	}
+
+	assert.NotNil(t, deleteCmd, "delete subcommand must exist")
+	assert.Equal(t, "delete <name>", deleteCmd.Use)
+	assert.Contains(t, deleteCmd.Short, "delete")
+	assert.NotEmpty(t, deleteCmd.Long)
+	assert.Contains(t, deleteCmd.Aliases, "rm", "delete should alias 'rm'")
+
+	// Verify it requires exactly 1 argument
+	assert.Error(t, deleteCmd.Args(deleteCmd, []string{}), "should reject zero args")
+	assert.NoError(t, deleteCmd.Args(deleteCmd, []string{"my-token"}), "should accept one arg")
+	assert.Error(t, deleteCmd.Args(deleteCmd, []string{"a", "b"}), "should reject two args")
+}
+
 func TestGetTokenCommand_IncludesRegenerate(t *testing.T) {
 	cmd := GetTokenCommand()
 
@@ -76,7 +101,7 @@ func TestGetMapString(t *testing.T) {
 
 	assert.Equal(t, "deploy-bot", getMapString(m, "name"))
 	assert.Equal(t, "", getMapString(m, "count"))       // not a string
-	assert.Equal(t, "", getMapString(m, "nonexistent"))  // missing key
+	assert.Equal(t, "", getMapString(m, "nonexistent")) // missing key
 }
 
 func TestJoinInterfaceSlice(t *testing.T) {

docs/features/agent-tokens.md

@@ -231,12 +231,23 @@ mcpproxy token show deploy-bot
 
 ### Revoke a Token
 
-Immediately invalidates the token:
+Immediately invalidates the token. Revoke is a **soft delete**: the record is kept
+(so the token name stays reserved) and any further use is rejected:
 
 ```bash
 mcpproxy token revoke deploy-bot
 ```
 
+### Delete a Token
+
+Permanently removes the token, freeing its name for reuse. Unlike revoke, delete
+removes the record entirely — after deleting, you can create a new token with the
+same name:
+
+```bash
+mcpproxy token delete deploy-bot   # aliases: rm, remove
+```
+
 ### Regenerate a Token
 
 Invalidates the old secret and generates a new one, keeping the same name and settings:
@@ -280,7 +291,8 @@ Agent tokens can also be managed via the REST API (requires admin API key):
 | `POST` | `/api/v1/tokens` | Create a new agent token |
 | `GET` | `/api/v1/tokens` | List all tokens |
 | `GET` | `/api/v1/tokens/{name}` | Get token details |
-| `DELETE` | `/api/v1/tokens/{name}` | Revoke a token |
+| `DELETE` | `/api/v1/tokens/{name}` | Revoke a token (soft delete; name stays reserved) |
+| `DELETE` | `/api/v1/tokens/{name}/permanent` | Permanently delete a token (frees the name for reuse) |
 | `POST` | `/api/v1/tokens/{name}/regenerate` | Regenerate token secret |
 
 ### Create Token via API

frontend/src/services/api.ts

@@ -1101,6 +1101,13 @@ class APIService {
     })
   }
 
+  // Permanently delete a token, freeing its name for reuse (unlike revoke, a soft delete).
+  async deleteAgentToken(name: string): Promise<APIResponse<void>> {
+    return this.request<void>(`/api/v1/tokens/${encodeURIComponent(name)}/permanent`, {
+      method: 'DELETE',
+    })
+  }
+
   async regenerateAgentToken(name: string): Promise<APIResponse<{ name: string; token: string }>> {
     return this.request<{ name: string; token: string }>(`/api/v1/tokens/${encodeURIComponent(name)}/regenerate`, {
       method: 'POST',

frontend/src/views/AgentTokens.vue

@@ -198,6 +198,17 @@
                   </svg>
                   Revoke
                 </button>
+                <button
+                  v-if="token.revoked || isExpired(token)"
+                  @click="handleDelete(token.name)"
+                  class="btn btn-xs btn-error"
+                  title="Permanently delete token and free its name for reuse"
+                >
+                  <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16" />
+                  </svg>
+                  Delete
+                </button>
               </div>
             </td>
           </tr>
@@ -643,6 +654,38 @@ async function handleRevoke(name: string) {
   }
 }
 
+// Permanently delete a (revoked or expired) token, freeing its name for reuse
+async function handleDelete(name: string) {
+  if (!confirm(`Permanently delete token "${name}"? This removes it completely and frees the name for reuse. This action cannot be undone.`)) {
+    return
+  }
+
+  try {
+    const response = await apiClient.deleteAgentToken(name)
+    if (response.success || !response.error) {
+      await loadTokens()
+
+      systemStore.addToast({
+        type: 'success',
+        title: 'Token Deleted',
+        message: `Token "${name}" has been permanently deleted`,
+      })
+    } else {
+      systemStore.addToast({
+        type: 'error',
+        title: 'Delete Failed',
+        message: response.error || 'Failed to delete token',
+      })
+    }
+  } catch (err: any) {
+    systemStore.addToast({
+      type: 'error',
+      title: 'Delete Failed',
+      message: err.message || 'Failed to delete token',
+    })
+  }
+}
+
 // Clipboard
 async function copyToken() {
   if (!newTokenSecret.value) return

internal/httpapi/auth_middleware_test.go

@@ -24,10 +24,11 @@ type testTokenStore struct {
 	validateFunc func(rawToken string, hmacKey []byte) (*auth.AgentToken, error)
 }
 
-func (s *testTokenStore) CreateAgentToken(_ auth.AgentToken, _ string, _ []byte) error   { return nil }
-func (s *testTokenStore) ListAgentTokens() ([]auth.AgentToken, error)                    { return nil, nil }
-func (s *testTokenStore) GetAgentTokenByName(_ string) (*auth.AgentToken, error)          { return nil, nil }
-func (s *testTokenStore) RevokeAgentToken(_ string) error                                 { return nil }
+func (s *testTokenStore) CreateAgentToken(_ auth.AgentToken, _ string, _ []byte) error { return nil }
+func (s *testTokenStore) ListAgentTokens() ([]auth.AgentToken, error)                  { return nil, nil }
+func (s *testTokenStore) GetAgentTokenByName(_ string) (*auth.AgentToken, error)       { return nil, nil }
+func (s *testTokenStore) RevokeAgentToken(_ string) error                              { return nil }
+func (s *testTokenStore) DeleteAgentToken(_ string) error                              { return nil }
 func (s *testTokenStore) RegenerateAgentToken(_ string, _ string, _ []byte) (*auth.AgentToken, error) {
 	return nil, nil
 }
@@ -398,4 +399,3 @@ func TestAPIKeyAuth_NoTokenStore_RejectsAgentToken(t *testing.T) {
 	assert.Equal(t, http.StatusUnauthorized, w.Code,
 		"Agent token should be rejected when token store is not configured")
 }
-

internal/httpapi/server.go

@@ -761,6 +761,7 @@ func (s *Server) setupRoutes() {
 			r.Route("/{name}", func(r chi.Router) {
 				r.Get("/", s.handleGetToken)
 				r.Delete("/", s.handleRevokeToken)
+				r.Delete("/permanent", s.handleDeleteToken)
 				r.Post("/regenerate", s.handleRegenerateToken)
 			})
 		})

internal/httpapi/tokens.go

@@ -22,6 +22,7 @@ type TokenStore interface {
 	ListAgentTokens() ([]auth.AgentToken, error)
 	GetAgentTokenByName(name string) (*auth.AgentToken, error)
 	RevokeAgentToken(name string) error
+	DeleteAgentToken(name string) error
 	RegenerateAgentToken(name string, newRawToken string, hmacKey []byte) (*auth.AgentToken, error)
 	ValidateAgentToken(rawToken string, hmacKey []byte) (*auth.AgentToken, error)
 	UpdateAgentTokenLastUsed(name string) error
@@ -292,6 +293,36 @@ func (s *Server) handleRevokeToken(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusNoContent)
 }
 
+// handleDeleteToken handles DELETE /api/v1/tokens/{name}/permanent
+// It permanently removes a token (unlike revoke, which is a soft delete),
+// freeing the name so it can be reused for a new token.
+func (s *Server) handleDeleteToken(w http.ResponseWriter, r *http.Request) {
+	if !s.requireAdminAuth(w, r) {
+		return
+	}
+	if !s.requireTokenStore(w, r) {
+		return
+	}
+
+	name := chi.URLParam(r, "name")
+	if name == "" {
+		s.writeError(w, r, http.StatusBadRequest, "Token name is required")
+		return
+	}
+
+	if err := s.tokenStore.DeleteAgentToken(name); err != nil {
+		if strings.Contains(err.Error(), "not found") {
+			s.writeError(w, r, http.StatusNotFound, fmt.Sprintf("Token %q not found", name))
+			return
+		}
+		s.logger.Errorf("Failed to delete agent token: %v", err)
+		s.writeError(w, r, http.StatusInternalServerError, "Failed to delete token")
+		return
+	}
+
+	w.WriteHeader(http.StatusNoContent)
+}
+
 // handleRegenerateToken handles POST /api/v1/tokens/{name}/regenerate
 func (s *Server) handleRegenerateToken(w http.ResponseWriter, r *http.Request) {
 	if !s.requireAdminAuth(w, r) {

internal/httpapi/tokens_test.go

@@ -24,6 +24,7 @@ type mockTokenStore struct {
 	tokens     map[string]auth.AgentToken
 	createErr  error
 	revokeErr  error
+	deleteErr  error
 	regenToken *auth.AgentToken
 	regenErr   error
 }
@@ -75,6 +76,17 @@ func (m *mockTokenStore) RevokeAgentToken(name string) error {
 	return nil
 }
 
+func (m *mockTokenStore) DeleteAgentToken(name string) error {
+	if m.deleteErr != nil {
+		return m.deleteErr
+	}
+	if _, ok := m.tokens[name]; !ok {
+		return fmt.Errorf("agent token %q not found", name)
+	}
+	delete(m.tokens, name)
+	return nil
+}
+
 func (m *mockTokenStore) ValidateAgentToken(rawToken string, _ []byte) (*auth.AgentToken, error) {
 	// Return a valid agent token for any mcp_agt_ prefixed token
 	if auth.ValidateTokenFormat(rawToken) {
@@ -628,6 +640,59 @@ func TestRevokeToken_NotFound(t *testing.T) {
 	assert.Equal(t, http.StatusNotFound, w.Code)
 }
 
+func TestDeleteToken(t *testing.T) {
+	store := newMockTokenStore()
+	srv := newTestTokenServer(t, store, nil)
+
+	// Create a token
+	body := createTokenRequest{
+		Name:        "delete-me",
+		Permissions: []string{"read"},
+	}
+	w := doRequest(t, srv, http.MethodPost, "/api/v1/tokens", body)
+	require.Equal(t, http.StatusCreated, w.Code)
+
+	// Permanently delete it
+	w = doRequest(t, srv, http.MethodDelete, "/api/v1/tokens/delete-me/permanent", nil)
+	assert.Equal(t, http.StatusNoContent, w.Code)
+
+	// Verify it's gone
+	stored, err := store.GetAgentTokenByName("delete-me")
+	require.NoError(t, err)
+	assert.Nil(t, stored)
+}
+
+func TestDeleteToken_NotFound(t *testing.T) {
+	store := newMockTokenStore()
+	srv := newTestTokenServer(t, store, nil)
+
+	w := doRequest(t, srv, http.MethodDelete, "/api/v1/tokens/nonexistent/permanent", nil)
+	assert.Equal(t, http.StatusNotFound, w.Code)
+}
+
+// TestDeleteToken_FreesNameForReuse verifies the issue #820 flow end-to-end at
+// the API layer: revoke reserves the name, delete frees it for reuse.
+func TestDeleteToken_FreesNameForReuse(t *testing.T) {
+	store := newMockTokenStore()
+	srv := newTestTokenServer(t, store, nil)
+
+	body := createTokenRequest{Name: "reusable", Permissions: []string{"read"}}
+	w := doRequest(t, srv, http.MethodPost, "/api/v1/tokens", body)
+	require.Equal(t, http.StatusCreated, w.Code)
+
+	// Revoke keeps the name reserved -> re-create conflicts.
+	w = doRequest(t, srv, http.MethodDelete, "/api/v1/tokens/reusable", nil)
+	require.Equal(t, http.StatusNoContent, w.Code)
+	w = doRequest(t, srv, http.MethodPost, "/api/v1/tokens", body)
+	assert.Equal(t, http.StatusConflict, w.Code)
+
+	// Permanent delete frees the name -> re-create succeeds.
+	w = doRequest(t, srv, http.MethodDelete, "/api/v1/tokens/reusable/permanent", nil)
+	require.Equal(t, http.StatusNoContent, w.Code)
+	w = doRequest(t, srv, http.MethodPost, "/api/v1/tokens", body)
+	assert.Equal(t, http.StatusCreated, w.Code)
+}
+
 func TestRegenerateToken(t *testing.T) {
 	store := newMockTokenStore()
 	srv := newTestTokenServer(t, store, nil)