feat: group-scoped API tokens with per-operation scopes (#1049)

## Summary
Adds CLI support for group-scoped platform API tokens. Companion to
turso-platform PRs #3755 / #3808 and dashboard PR
tursodatabase/dashboard#811.

### Mint
```
turso auth api-tokens mint <name> --org <slug> --group <group> --scope <label> ...
turso auth api-tokens mint <name> --org <slug> --group <group> --read-only
turso auth api-tokens mint <name> --org <slug> --group <group> --full-access
```

- `--group <name>` pins the token to a single group inside `--org`.
- `--scope <label>` (repeatable) grants individual scopes. Allowed
values: `read`, `db:create`, `db:delete`, `db:configure`,
`db:mint-token`, `db:rotate-creds`, `group:configure`,
`group:mint-token`, `group:rotate-creds`.
- `--read-only` / `--full-access` are preset shorthands — the platform
expands them server-side.
- Mint and rotate are separate scopes so granting "issue SQL
credentials" does not also grant "invalidate every running app's
credentials."
- Unknown scopes are rejected client-side so typos surface without a
round-trip.
- Group existence is validated before the create POST (`Groups.Get`
against the requested `--org`), giving a clear local error instead of a
404 from the token endpoint.

### List
The token table now shows:
- "Organization" column → **Scope**: `all` for unrestricted, `<org>` for
org-scoped, `<org>/<group>` for group-scoped.
- New **Permissions** column: `—` for tokens without a scope set,
`read-only` when the only scope is `read`, `full-access` when every
known scope is present, otherwise the comma-separated scope list.

Preset recognition runs over the expanded scope set the platform stores;
the preset names themselves are inputs only and never round-trip.

## Files
- `internal/turso/apitoken_scope.go` (new) — scope vocabulary mirroring
the platform's `api/service/scope/scope.go`
- `internal/turso/apiTokens.go` — `ApiToken` gains `Group` + `Scopes`;
new `CreateScoped(name, org, group, scopes)`; old `CreateWithOrg` kept
as a thin wrapper
- `internal/cmd/auth_createapitokens.go` — new flags + validation +
group existence check
- `internal/cmd/auth_listapitokens.go` — Scope + Permissions columns

## Test plan
- [x] `go build ./...`
- [x] `go vet ./...`
- [x] Manual smoke test by author: minted org-scoped, group-scoped
`--read-only`, group-scoped custom, group-scoped `--full-access`; `list`
renders all four flavors correctly.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: glommer

internal/cmd/auth_createapitokens.go

@@ -6,21 +6,35 @@ import (
 
 	"github.com/spf13/cobra"
 	"github.com/tursodatabase/turso-cli/internal"
+	"github.com/tursodatabase/turso-cli/internal/turso"
 )
 
-var mintOrgFlag string
+var (
+	mintOrgFlag        string
+	mintGroupFlag      string
+	mintScopeFlags     []string
+	mintReadOnlyFlag   bool
+	mintFullAccessFlag bool
+)
 
 func init() {
 	apiTokensCmd.AddCommand(createApiTokensCmd)
-	createApiTokensCmd.Flags().StringVar(&mintOrgFlag, "org", "", "Organization to restrict the token to")
+	createApiTokensCmd.Flags().StringVar(&mintOrgFlag, "org", "", "Organization to restrict the token to.")
+	createApiTokensCmd.Flags().StringVar(&mintGroupFlag, "group", "", "Group inside --org to restrict the token to. Implies --org and requires at least one scope.")
+	createApiTokensCmd.Flags().StringArrayVar(&mintScopeFlags, "scope", nil, "Permission scope to grant to a group-scoped token. May be repeated. Allowed values: "+scopeFlagListing()+".")
+	createApiTokensCmd.Flags().BoolVar(&mintReadOnlyFlag, "read-only", false, "Shorthand for --scope read.")
+	createApiTokensCmd.Flags().BoolVar(&mintFullAccessFlag, "full-access", false, "Shorthand for granting every scope. Use with care; equivalent to a deployer that can create, delete, configure, mint and rotate.")
 }
 
 var createApiTokensCmd = &cobra.Command{
 	Use:   "mint <api-token-name>",
 	Short: "Mint an API token.",
 	Long: "" +
 		"API tokens are revocable non-expiring tokens that authenticate holders as the user who minted them.\n" +
-		"They can be used to implement automations with the " + internal.Emph("turso") + " CLI or the platform API.",
+		"They can be used to implement automations with the " + internal.Emph("turso") + " CLI or the platform API.\n" +
+		"\n" +
+		"With --group, the token is restricted to a single group inside the organization and to the\n" +
+		"set of scopes you pass via --scope (or the --read-only / --full-access shorthands).",
 	Args: cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		cmd.SilenceUsage = true
@@ -32,27 +46,35 @@ var createApiTokensCmd = &cobra.Command{
 
 		name := strings.TrimSpace(args[0])
 
-		// Validate organization if provided
-		if mintOrgFlag != "" {
-			orgs, err := client.Organizations.List()
-			if err != nil {
-				return fmt.Errorf("failed to list organizations: %w", err)
+		scopes, err := resolveMintScopes()
+		if err != nil {
+			return err
+		}
+
+		if mintGroupFlag != "" {
+			if mintOrgFlag == "" {
+				return fmt.Errorf("--group requires --org")
 			}
+			if len(scopes) == 0 {
+				return fmt.Errorf("--group requires at least one scope (use --scope, --read-only, or --full-access)")
+			}
+		} else if len(scopes) > 0 {
+			return fmt.Errorf("--scope / --read-only / --full-access are only meaningful with --group")
+		}
 
-			found := false
-			for _, org := range orgs {
-				if org.Slug == mintOrgFlag {
-					found = true
-					break
-				}
+		if mintOrgFlag != "" {
+			if err := validateOrgExists(client, mintOrgFlag); err != nil {
+				return err
 			}
+		}
 
-			if !found {
-				return fmt.Errorf("organization %s not found", internal.Emph(mintOrgFlag))
+		if mintGroupFlag != "" {
+			if err := validateGroupExists(client, mintOrgFlag, mintGroupFlag); err != nil {
+				return err
 			}
 		}
 
-		data, err := client.ApiTokens.CreateWithOrg(name, mintOrgFlag)
+		data, err := client.ApiTokens.CreateScoped(name, mintOrgFlag, mintGroupFlag, scopes)
 		if err != nil {
 			return err
 		}
@@ -61,3 +83,79 @@ var createApiTokensCmd = &cobra.Command{
 		return nil
 	},
 }
+
+// resolveMintScopes turns the --scope / --read-only / --full-access flags
+// into the list of scope strings sent to the platform. Conflicting flag
+// combinations (e.g. --read-only with --full-access) are rejected, and
+// individual scope labels are validated client-side so typos surface
+// without a round-trip.
+func resolveMintScopes() ([]string, error) {
+	if mintReadOnlyFlag && mintFullAccessFlag {
+		return nil, fmt.Errorf("--read-only and --full-access are mutually exclusive")
+	}
+	if (mintReadOnlyFlag || mintFullAccessFlag) && len(mintScopeFlags) > 0 {
+		return nil, fmt.Errorf("--scope cannot be combined with --read-only or --full-access; use one or the other")
+	}
+	if mintReadOnlyFlag {
+		return []string{"read-only"}, nil
+	}
+	if mintFullAccessFlag {
+		return []string{"full-access"}, nil
+	}
+	if len(mintScopeFlags) == 0 {
+		return nil, nil
+	}
+	out := make([]string, 0, len(mintScopeFlags))
+	seen := make(map[string]struct{}, len(mintScopeFlags))
+	for _, raw := range mintScopeFlags {
+		s := strings.TrimSpace(raw)
+		if s == "" {
+			continue
+		}
+		if !turso.IsValidScope(s) {
+			return nil, fmt.Errorf("unknown scope %s. Allowed: %s", internal.Emph(s), scopeFlagListing())
+		}
+		if _, dup := seen[s]; dup {
+			continue
+		}
+		seen[s] = struct{}{}
+		out = append(out, s)
+	}
+	return out, nil
+}
+
+func validateOrgExists(client *turso.Client, slug string) error {
+	orgs, err := client.Organizations.List()
+	if err != nil {
+		return fmt.Errorf("failed to list organizations: %w", err)
+	}
+	for _, org := range orgs {
+		if org.Slug == slug {
+			return nil
+		}
+	}
+	return fmt.Errorf("organization %s not found", internal.Emph(slug))
+}
+
+// validateGroupExists confirms that the named group lives inside the given
+// organization slug. The Groups client URL-builds from client.Org, so we
+// temporarily point the client at the target org for the lookup, then
+// restore. (Single-command invocation, no concurrency to worry about.)
+func validateGroupExists(client *turso.Client, orgSlug, groupName string) error {
+	savedOrg := client.Org
+	client.Org = orgSlug
+	defer func() { client.Org = savedOrg }()
+
+	if _, err := client.Groups.Get(groupName); err != nil {
+		return fmt.Errorf("group %s not found in organization %s: %w", internal.Emph(groupName), internal.Emph(orgSlug), err)
+	}
+	return nil
+}
+
+func scopeFlagListing() string {
+	parts := make([]string, 0, len(turso.AllScopes))
+	for _, s := range turso.AllScopes {
+		parts = append(parts, string(s))
+	}
+	return strings.Join(parts, ", ")
+}

internal/cmd/auth_listapitokens.go

@@ -1,8 +1,12 @@
 package cmd
 
 import (
+	"sort"
+	"strings"
+
 	"github.com/spf13/cobra"
 	"github.com/tursodatabase/turso-cli/internal"
+	"github.com/tursodatabase/turso-cli/internal/turso"
 )
 
 func init() {
@@ -31,14 +35,67 @@ var listApiTokensCmd = &cobra.Command{
 
 		data := [][]string{}
 		for _, apiToken := range apiTokens {
-			org := apiToken.Organization
-			if org == "" {
-				org = "all"
-			}
-			data = append(data, []string{apiToken.Name, org, apiToken.CreatedAt})
+			data = append(data, []string{
+				apiToken.Name,
+				formatTokenOrgScope(apiToken),
+				formatTokenPermissions(apiToken),
+				apiToken.CreatedAt,
+			})
 		}
-		printTable([]string{"Name", "Organization", "Created At"}, data)
+		printTable([]string{"Name", "Scope", "Permissions", "Created At"}, data)
 
 		return nil
 	},
 }
+
+// formatTokenOrgScope renders the token's binding for the "Scope" column:
+// unrestricted tokens read "all", org-scoped tokens show the org slug, and
+// group-scoped tokens show "<org>/<group>". The slash form keeps the column
+// narrow while making the boundary visible at a glance.
+func formatTokenOrgScope(t turso.ApiToken) string {
+	switch {
+	case t.Organization == "":
+		return "all"
+	case t.Group == "":
+		return t.Organization
+	default:
+		return t.Organization + "/" + t.Group
+	}
+}
+
+// formatTokenPermissions summarizes the scope list for the "Permissions"
+// column. The platform expands presets to their underlying scopes server-side,
+// so we recognize the canonical preset shapes here ("read-only" = just
+// `read`, "full-access" = every known scope) for a friendlier label;
+// anything else is listed verbatim.
+func formatTokenPermissions(t turso.ApiToken) string {
+	if len(t.Scopes) == 0 {
+		return "—"
+	}
+	scopes := append([]string(nil), t.Scopes...)
+	sort.Strings(scopes)
+	if len(scopes) == 1 && scopes[0] == string(turso.ScopeRead) {
+		return "read-only"
+	}
+	if isFullAccessScopeSet(scopes) {
+		return "full-access"
+	}
+	return strings.Join(scopes, ", ")
+}
+
+func isFullAccessScopeSet(sortedScopes []string) bool {
+	if len(sortedScopes) != len(turso.AllScopes) {
+		return false
+	}
+	reference := make([]string, 0, len(turso.AllScopes))
+	for _, s := range turso.AllScopes {
+		reference = append(reference, string(s))
+	}
+	sort.Strings(reference)
+	for i, s := range sortedScopes {
+		if s != reference[i] {
+			return false
+		}
+	}
+	return true
+}

internal/turso/apiTokens.go

@@ -8,12 +8,14 @@ import (
 )
 
 type ApiToken struct {
-	ID           string `json:"id"`
-	Name         string `json:"name"`
-	Organization string `json:"organization,omitempty"`
-	CreatedAt    string `json:"created_at"`
-	Owner        uint   `json:"-"`
-	PubKey       []byte `json:"-"`
+	ID           string   `json:"id"`
+	Name         string   `json:"name"`
+	Organization string   `json:"organization,omitempty"`
+	Group        string   `json:"group,omitempty"`
+	Scopes       []string `json:"scopes,omitempty"`
+	CreatedAt    string   `json:"created_at"`
+	Owner        uint     `json:"-"`
+	PubKey       []byte   `json:"-"`
 }
 
 type ApiTokensClient client
@@ -47,16 +49,33 @@ func (a *ApiTokensClient) Create(name string) (CreateApiToken, error) {
 }
 
 func (a *ApiTokensClient) CreateWithOrg(name string, organization string) (CreateApiToken, error) {
+	return a.CreateScoped(name, organization, "", nil)
+}
+
+// CreateScoped mints an API token with optional restrictions. Empty
+// organization minted an unrestricted token. organization + empty group
+// produces an organization-scoped token. organization + group + non-empty
+// scopes produces a group-scoped token; the platform requires the scopes
+// list to be non-empty in that case.
+//
+// scopes may contain individual scope labels (see AllScopes) or the
+// preset names "read-only" / "full-access" — the platform expands the
+// presets server-side.
+func (a *ApiTokensClient) CreateScoped(name, organization, group string, scopes []string) (CreateApiToken, error) {
 	url := fmt.Sprintf("/v2/auth/api-tokens/%s", name)
 
 	var res *http.Response
 	var err error
 
-	if organization != "" {
+	if organization != "" || group != "" || len(scopes) > 0 {
 		reqBody := struct {
-			Organization string `json:"organization"`
+			Organization string   `json:"organization,omitempty"`
+			Group        string   `json:"group,omitempty"`
+			Scopes       []string `json:"scopes,omitempty"`
 		}{
 			Organization: organization,
+			Group:        group,
+			Scopes:       scopes,
 		}
 		jsonData, marshalErr := json.Marshal(reqBody)
 		if marshalErr != nil {

internal/turso/apitoken_scope.go

@@ -0,0 +1,45 @@
+package turso
+
+// Scope is a permission label carried by a group-scoped platform API token.
+// The vocabulary mirrors api/service/scope/scope.go on the platform side; if
+// the platform adds or renames scopes, this file must follow.
+type Scope string
+
+const (
+	ScopeRead             Scope = "read"
+	ScopeDbCreate         Scope = "db:create"
+	ScopeDbDelete         Scope = "db:delete"
+	ScopeDbConfigure      Scope = "db:configure"
+	ScopeDbMintToken      Scope = "db:mint-token"
+	ScopeDbRotateCreds    Scope = "db:rotate-creds"
+	ScopeGroupConfigure   Scope = "group:configure"
+	ScopeGroupMintToken   Scope = "group:mint-token"
+	ScopeGroupRotateCreds Scope = "group:rotate-creds"
+)
+
+// AllScopes is the canonical ordering used by --help output and the
+// individual-scope validator. Presets ("read-only", "full-access") are
+// accepted by the platform but not listed here — they're handled as
+// separate CLI flags.
+var AllScopes = []Scope{
+	ScopeRead,
+	ScopeDbCreate,
+	ScopeDbDelete,
+	ScopeDbConfigure,
+	ScopeDbMintToken,
+	ScopeDbRotateCreds,
+	ScopeGroupConfigure,
+	ScopeGroupMintToken,
+	ScopeGroupRotateCreds,
+}
+
+// IsValidScope reports whether s is a known scope label. Used to surface
+// typos client-side instead of waiting for the platform 400.
+func IsValidScope(s string) bool {
+	for _, sc := range AllScopes {
+		if string(sc) == s {
+			return true
+		}
+	}
+	return false
+}