Merge pull request #195 from agesta23/feat/account-scoped-tokens

feat: add support for account-scoped API tokens

Author: haad

README.md

@@ -26,6 +26,10 @@ Authentication towards the Cloudflare API can be done in two ways:
 The preferred way of authenticating is with an API token, for which the scope can be configured at the Cloudflare
 dashboard.
 
+**Important**: Cloudflare supports two types of API tokens:
+- **User-level tokens**: Can access all accounts the user has permissions for. These tokens auto-discover all accessible accounts.
+- **Account-scoped tokens**: Scoped to a specific account. When using account-scoped tokens, you **must** set the `CF_ACCOUNTS` environment variable with your account ID(s).
+
 Required authentication scopes:
 
 - `Zone/Analytics:Read` is required for zone-level metrics
@@ -37,9 +41,15 @@ Required authentication scopes:
 - `Account:Load Balancing: Monitors and Pools:Read` is required to fetch pools origin health status `cloudflare_pool_origin_health_status` metric
 - `Cloudflare Tunnel Read` is required to fetch Cloudflare Tunnel (Cloudflare Zero Trust) metrics
 
-To authenticate this way, only set `CF_API_TOKEN` (omit `CF_API_EMAIL` and `CF_API_KEY`)
+**To authenticate with a user-level token**:
+- Set `CF_API_TOKEN` (omit `CF_API_EMAIL` and `CF_API_KEY`)
+- The exporter will auto-discover all accounts you have access to
+- [Shortcut to create the API token](https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22account_analytics%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22account_settings%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22analytics%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22firewall_services%22%2C%22type%22%3A%22read%22%7D%5D&name=Cloudflare+Exporter&accountId=*&zoneId=all)
 
-[Shortcut to create the API token](https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22account_analytics%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22account_settings%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22analytics%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22firewall_services%22%2C%22type%22%3A%22read%22%7D%5D&name=Cloudflare+Exporter&accountId=*&zoneId=all)
+**To authenticate with an account-scoped token**:
+- Set `CF_API_TOKEN` with your account-scoped token
+- Set `CF_ACCOUNTS` with your account ID (find it in the Cloudflare dashboard URL: `https://dash.cloudflare.com/<ACCOUNT_ID>/...`)
+- Example: `CF_ACCOUNTS=abc123def456` or for multiple accounts: `CF_ACCOUNTS=abc123,def456`
 
 ### User email + API key
 
@@ -57,6 +67,7 @@ The exporter can be configured using env variables or command flags.
 | `CF_API_EMAIL` |  user email (see <https://support.cloudflare.com/hc/en-us/articles/200167836-Managing-API-Tokens-and-Keys>) |
 | `CF_API_KEY` |  API key associated with email (`CF_API_EMAIL` is required if this is set)|
 | `CF_API_TOKEN` |  API authentication token (recommended before API key + email. Version 0.0.5+. see <https://developers.cloudflare.com/analytics/graphql-api/getting-started/authentication/api-token-auth>) |
+| `CF_ACCOUNTS` |  (Required for account-scoped tokens) Cloudflare account IDs to monitor, comma delimited list. When using account-scoped API tokens, this must be set. User-level tokens can omit this to auto-discover all accessible accounts. |
 | `CF_ZONES` |  (Optional) cloudflare zones to export, comma delimited list of zone ids. If not set, all zones from account are exported |
 | `CF_EXCLUDE_ZONES` |  (Optional) cloudflare zones to exclude, comma delimited list of zone ids. If not set, no zones from account are excluded |
 | `CF_TIMEOUT` | Set cloudflare request timeout. Default 10 seconds |
@@ -77,6 +88,7 @@ Corresponding flags:
   -cf_api_email="": cloudflare api email, works with api_key flag
   -cf_api_key="": cloudflare api key, works with api_email flag
   -cf_api_token="": cloudflare api token (version 0.0.5+, preferred)
+  -cf_accounts="": cloudflare accounts to monitor, comma delimited list (required for account-scoped API tokens)
   -cf_zones="": cloudflare zones to export, comma delimited list
   -cf_exclude_zones="": cloudflare zones to exclude, comma delimited list
   -cf_timeout="10s": cloudflare request timeout, default 10 seconds

cloudflare.go

@@ -458,8 +458,37 @@ func fetchFirewallRules(zoneID string) map[string]string {
 	return firewallRulesMap
 }
 
-func fetchAccounts() []cfaccounts.Account {
+func fetchAccounts(targetAccountIDs []string) []cfaccounts.Account {
 	var cfAccounts []cfaccounts.Account
+
+	if len(targetAccountIDs) > 0 {
+		log.Info("Using provided account IDs (account-scoped token mode)")
+		for _, accountID := range targetAccountIDs {
+			accountID = strings.TrimSpace(accountID)
+			if accountID == "" {
+				continue
+			}
+
+			ctx, cancel := context.WithTimeout(context.Background(), cftimeout)
+			account, err := cfclient.Accounts.Get(ctx, cfaccounts.AccountGetParams{
+				AccountID: cf.F(accountID),
+			})
+			cancel()
+
+			if err != nil {
+				log.Warnf("Account %s details unavailable, using ID only: %v", accountID, err)
+				cfAccounts = append(cfAccounts, cfaccounts.Account{
+					ID: accountID,
+				})
+			} else {
+				cfAccounts = append(cfAccounts, *account)
+			}
+		}
+		log.Infof("Loaded %d account(s) from CF_ACCOUNTS", len(cfAccounts))
+		return cfAccounts
+	}
+
+	log.Info("Listing all accessible accounts (user-level token mode)")
 	ctx, cancel := context.WithTimeout(context.Background(), cftimeout)
 	defer cancel()
 	page := cfclient.Accounts.ListAutoPaging(ctx,

main.go

@@ -39,6 +39,15 @@ var (
 // 	cfgMetricsDenylist = ""
 // )
 
+func getTargetAccounts() []string {
+	var accountIDs []string
+
+	if len(viper.GetString("cf_accounts")) > 0 {
+		accountIDs = strings.Split(viper.GetString("cf_accounts"), ",")
+	}
+	return accountIDs
+}
+
 func getTargetZones() []string {
 	var zoneIDs []string
 
@@ -105,7 +114,8 @@ func filterExcludedZones(all []cfzones.Zone, exclude []string) []cfzones.Zone {
 
 func fetchMetrics() {
 	var wg sync.WaitGroup
-	accounts := fetchAccounts()
+	targetAccounts := getTargetAccounts()
+	accounts := fetchAccounts(targetAccounts)
 
 	for _, a := range accounts {
 		wg.Add(1)
@@ -257,6 +267,10 @@ func main() {
 	flags.String("cf_api_token", "", "cloudflare api token (preferred)")
 	viper.BindEnv("cf_api_token")
 
+	flags.String("cf_accounts", "", "cloudflare accounts to monitor, comma delimited list of account ids (required for account-scoped API tokens)")
+	viper.BindEnv("cf_accounts")
+	viper.SetDefault("cf_accounts", "")
+
 	flags.String("cf_zones", "", "cloudflare zones to export, comma delimited list of zone ids")
 	viper.BindEnv("cf_zones")
 	viper.SetDefault("cf_zones", "")