feat: add external API key scopes (#19916)

# Add support for low-level API key scopes

This PR adds support for fine-grained API key scopes based on RBAC resource:action pairs. It includes:

1. A new endpoint `/api/v2/auth/scopes` to list all public low-level API key scopes
2. Generated constants in the SDK for all public scopes
3. Tests to verify scope validation during token creation
4. Updated API documentation to reflect the expanded scope options

The implementation allows users to create API keys with specific permissions like `workspace:read` or `template:use` instead of only the legacy `all` or `application_connect` scopes.



Fixes #19847

codersdk/apikey.go

@@ -42,17 +42,9 @@ const (
 
 type APIKeyScope string
 
-const (
-	// APIKeyScopeAll is a scope that allows the user to do everything.
-	APIKeyScopeAll APIKeyScope = "all"
-	// APIKeyScopeApplicationConnect is a scope that allows the user
-	// to connect to applications in a workspace.
-	APIKeyScopeApplicationConnect APIKeyScope = "application_connect"
-)
-
 type CreateTokenRequest struct {
 	Lifetime  time.Duration `json:"lifetime"`
-	Scope     APIKeyScope   `json:"scope" enums:"all,application_connect"`
+	Scope     APIKeyScope   `json:"scope"`
 	TokenName string        `json:"token_name"`
 }
 

codersdk/apikey_scopes_gen.go

@@ -0,0 +1,73 @@
+// Code generated by scripts/apikeyscopesgen. DO NOT EDIT.
+package codersdk
+
+const (
+	APIKeyScopeAll                         APIKeyScope = "all"
+	APIKeyScopeApiKeyAll                   APIKeyScope = "api_key:*"
+	APIKeyScopeApiKeyCreate                APIKeyScope = "api_key:create"
+	APIKeyScopeApiKeyDelete                APIKeyScope = "api_key:delete"
+	APIKeyScopeApiKeyRead                  APIKeyScope = "api_key:read"
+	APIKeyScopeApiKeyUpdate                APIKeyScope = "api_key:update"
+	APIKeyScopeApplicationConnect          APIKeyScope = "application_connect"
+	APIKeyScopeFileAll                     APIKeyScope = "file:*"
+	APIKeyScopeFileCreate                  APIKeyScope = "file:create"
+	APIKeyScopeFileRead                    APIKeyScope = "file:read"
+	APIKeyScopeTemplateAll                 APIKeyScope = "template:*"
+	APIKeyScopeTemplateCreate              APIKeyScope = "template:create"
+	APIKeyScopeTemplateDelete              APIKeyScope = "template:delete"
+	APIKeyScopeTemplateRead                APIKeyScope = "template:read"
+	APIKeyScopeTemplateUpdate              APIKeyScope = "template:update"
+	APIKeyScopeTemplateUse                 APIKeyScope = "template:use"
+	APIKeyScopeUserReadPersonal            APIKeyScope = "user:read_personal"
+	APIKeyScopeUserUpdatePersonal          APIKeyScope = "user:update_personal"
+	APIKeyScopeUserSecretAll               APIKeyScope = "user_secret:*"
+	APIKeyScopeUserSecretCreate            APIKeyScope = "user_secret:create"
+	APIKeyScopeUserSecretDelete            APIKeyScope = "user_secret:delete"
+	APIKeyScopeUserSecretRead              APIKeyScope = "user_secret:read"
+	APIKeyScopeUserSecretUpdate            APIKeyScope = "user_secret:update"
+	APIKeyScopeWorkspaceAll                APIKeyScope = "workspace:*"
+	APIKeyScopeWorkspaceApplicationConnect APIKeyScope = "workspace:application_connect"
+	APIKeyScopeWorkspaceCreate             APIKeyScope = "workspace:create"
+	APIKeyScopeWorkspaceDelete             APIKeyScope = "workspace:delete"
+	APIKeyScopeWorkspaceRead               APIKeyScope = "workspace:read"
+	APIKeyScopeWorkspaceSsh                APIKeyScope = "workspace:ssh"
+	APIKeyScopeWorkspaceStart              APIKeyScope = "workspace:start"
+	APIKeyScopeWorkspaceStop               APIKeyScope = "workspace:stop"
+	APIKeyScopeWorkspaceUpdate             APIKeyScope = "workspace:update"
+)
+
+// PublicAPIKeyScopes lists all public low-level API key scopes.
+var PublicAPIKeyScopes = []APIKeyScope{
+	APIKeyScopeAll,
+	APIKeyScopeApiKeyAll,
+	APIKeyScopeApiKeyCreate,
+	APIKeyScopeApiKeyDelete,
+	APIKeyScopeApiKeyRead,
+	APIKeyScopeApiKeyUpdate,
+	APIKeyScopeApplicationConnect,
+	APIKeyScopeFileAll,
+	APIKeyScopeFileCreate,
+	APIKeyScopeFileRead,
+	APIKeyScopeTemplateAll,
+	APIKeyScopeTemplateCreate,
+	APIKeyScopeTemplateDelete,
+	APIKeyScopeTemplateRead,
+	APIKeyScopeTemplateUpdate,
+	APIKeyScopeTemplateUse,
+	APIKeyScopeUserReadPersonal,
+	APIKeyScopeUserUpdatePersonal,
+	APIKeyScopeUserSecretAll,
+	APIKeyScopeUserSecretCreate,
+	APIKeyScopeUserSecretDelete,
+	APIKeyScopeUserSecretRead,
+	APIKeyScopeUserSecretUpdate,
+	APIKeyScopeWorkspaceAll,
+	APIKeyScopeWorkspaceApplicationConnect,
+	APIKeyScopeWorkspaceCreate,
+	APIKeyScopeWorkspaceDelete,
+	APIKeyScopeWorkspaceRead,
+	APIKeyScopeWorkspaceSsh,
+	APIKeyScopeWorkspaceStart,
+	APIKeyScopeWorkspaceStop,
+	APIKeyScopeWorkspaceUpdate,
+}

codersdk/scopes_catalog.go

@@ -0,0 +1,5 @@
+package codersdk
+
+type ExternalAPIKeyScopes struct {
+	External []APIKeyScope `json:"external"`
+}