feat(api-tokens): replace include_revoked boolean with StatusFilter enum (#2746)

Signed-off-by: Miguel Martinez <miguel@chainloop.dev>

Author: migmartri

app/cli/cmd/organization_apitoken_list.go

@@ -1,5 +1,5 @@
 //
-// Copyright 2023-2025 The Chainloop Authors.
+// Copyright 2023-2026 The Chainloop Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -28,6 +28,7 @@ import (
 func newAPITokenListCmd() *cobra.Command {
 	var (
 		includeRevoked bool
+		statusFilter   string
 		project        string
 		scope          string
 	)
@@ -37,6 +38,12 @@ func newAPITokenListCmd() *cobra.Command {
 		"global",
 	}
 
+	var availableStatusFilters = []string{
+		"active",
+		"revoked",
+		"all",
+	}
+
 	cmd := &cobra.Command{
 		Use:     "list",
 		Aliases: []string{"ls"},
@@ -46,10 +53,22 @@ func newAPITokenListCmd() *cobra.Command {
 				return fmt.Errorf("invalid scope %q, please chose one of: %v", scope, availableScopes)
 			}
 
+			if statusFilter != "" && !slices.Contains(availableStatusFilters, statusFilter) {
+				return fmt.Errorf("invalid status %q, please choose one of: %v", statusFilter, availableStatusFilters)
+			}
+
 			return nil
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
-			res, err := action.NewAPITokenList(ActionOpts).Run(context.Background(), includeRevoked, project, scope)
+			// --all is deprecated: map it to --status all
+			if includeRevoked {
+				cmd.PrintErr("Warning: --all is deprecated, use --status all instead\n")
+				if statusFilter == "" {
+					statusFilter = "all"
+				}
+			}
+
+			res, err := action.NewAPITokenList(ActionOpts).Run(context.Background(), statusFilter, project, scope)
 			if err != nil {
 				return fmt.Errorf("listing API tokens: %w", err)
 			}
@@ -58,7 +77,11 @@ func newAPITokenListCmd() *cobra.Command {
 		},
 	}
 
-	cmd.Flags().BoolVarP(&includeRevoked, "all", "a", false, "show all API tokens including revoked ones")
+	cmd.Flags().BoolVarP(&includeRevoked, "all", "a", false, "Deprecated: use --status all instead")
+	if err := cmd.Flags().MarkDeprecated("all", "use --status all instead"); err != nil {
+		panic(err)
+	}
+	cmd.Flags().StringVar(&statusFilter, "status", "", fmt.Sprintf("filter by token status, available values: %v", availableStatusFilters))
 	cmd.Flags().StringVarP(&project, "project", "p", "", "filter by project name")
 	cmd.Flags().StringVarP(&scope, "scope", "s", "", fmt.Sprintf("filter by scope, available scopes: %v", availableScopes))
 	return cmd

app/cli/documentation/cli-reference.mdx

@@ -2139,10 +2139,10 @@ chainloop organization api-token list [flags]
 Options
 
 ```
--a, --all              show all API tokens including revoked ones
 -h, --help             help for list
 -p, --project string   filter by project name
 -s, --scope string     filter by scope, available scopes: [project global]
+--status string    filter by token status, available values: [active revoked all]
 ```
 
 Options inherited from parent commands

app/cli/pkg/action/apitoken_list.go

@@ -1,5 +1,5 @@
 //
-// Copyright 2024-2025 The Chainloop Authors.
+// Copyright 2024-2026 The Chainloop Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -30,10 +30,10 @@ func NewAPITokenList(cfg *ActionsOpts) *APITokenList {
 	return &APITokenList{cfg}
 }
 
-func (action *APITokenList) Run(ctx context.Context, includeRevoked bool, project string, scope string) ([]*APITokenItem, error) {
+func (action *APITokenList) Run(ctx context.Context, statusFilter string, project string, scope string) ([]*APITokenItem, error) {
 	client := pb.NewAPITokenServiceClient(action.cfg.CPConnection)
 
-	req := &pb.APITokenServiceListRequest{IncludeRevoked: includeRevoked}
+	req := &pb.APITokenServiceListRequest{StatusFilter: mapStatusFilter(statusFilter)}
 	if project != "" {
 		req.Project = &pb.IdentityReference{Name: &project}
 	}
@@ -65,3 +65,14 @@ func mapScope(scope string) pb.APITokenServiceListRequest_Scope {
 		return pb.APITokenServiceListRequest_SCOPE_UNSPECIFIED
 	}
 }
+
+func mapStatusFilter(status string) pb.APITokenServiceListRequest_StatusFilter {
+	switch status {
+	case "revoked":
+		return pb.APITokenServiceListRequest_STATUS_FILTER_REVOKED
+	case "all":
+		return pb.APITokenServiceListRequest_STATUS_FILTER_ALL
+	default:
+		return pb.APITokenServiceListRequest_STATUS_FILTER_ACTIVE
+	}
+}

app/controlplane/api/controlplane/v1/api_token.pb.go

@@ -1,5 +1,5 @@
 //
-// Copyright 2024-2025 The Chainloop Authors.
+// Copyright 2024-2026 The Chainloop Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -55,7 +55,8 @@ message APITokenServiceRevokeRequest {
 message APITokenServiceRevokeResponse {}
 
 message APITokenServiceListRequest {
-  bool include_revoked = 1;
+  // Deprecated: use status_filter instead.
+  bool include_revoked = 1 [deprecated = true];
 
   // optional project reference to filter by
   IdentityReference project = 4;
@@ -68,6 +69,21 @@ message APITokenServiceListRequest {
 
   // filter by the scope of the token
   Scope scope = 2;
+
+  // buf:lint:ignore ENUM_ZERO_VALUE_SUFFIX
+  // STATUS_FILTER_ACTIVE = 0 is intentional: active tokens are the default,
+  // matching proto3 zero-value semantics and preserving backward compatibility.
+  enum StatusFilter {
+    // Only active (non-revoked) tokens. This is the default.
+    STATUS_FILTER_ACTIVE = 0;
+    // Only revoked tokens.
+    STATUS_FILTER_REVOKED = 1;
+    // All tokens regardless of revocation status.
+    STATUS_FILTER_ALL = 2;
+  }
+
+  // Filter tokens by their revocation status. Defaults to STATUS_FILTER_ACTIVE.
+  StatusFilter status_filter = 5;
 }
 
 message APITokenServiceListResponse {