feat: support custom token endpoint from service account credentials

- Extended `KeyFlowConfig` with a `GetCredentialsTokenEndpoint` helper
  to safely extract custom token URLs from service account credentials.
- Updated `KeyFlow.Init` to use the new helper, allowing the flow to
  fallback to the default `tokenAPI` gracefully if no custom endpoint
  is provided.
- Added standard Go doc comments for KeyFlow methods.
- Expanded `TestKeyFlowInit` to assert the resolved TokenUrl and added
  a new test scenario to verify the custom endpoint logic.

Author: stackitcarlos

core/clients/key_flow.go

@@ -78,11 +78,12 @@ type ServiceAccountKeyResponse struct {
 }
 
 type ServiceAccountKeyCredentials struct {
-	Aud        string    `json:"aud"`
-	Iss        string    `json:"iss"`
-	Kid        string    `json:"kid"`
-	PrivateKey *string   `json:"privateKey,omitempty"`
-	Sub        uuid.UUID `json:"sub"`
+	Aud           string    `json:"aud"`
+	Iss           string    `json:"iss"`
+	Kid           string    `json:"kid"`
+	PrivateKey    *string   `json:"privateKey,omitempty"`
+	Sub           uuid.UUID `json:"sub"`
+	TokenEndpoint string    `json:"tokenEndpoint"`
 }
 
 // GetConfig returns the flow configuration
@@ -117,13 +118,26 @@ func (c *KeyFlow) GetToken() TokenResponseBody {
 	return *c.token
 }
 
+// GetCredentialsTokenEndpoint returns the token endpoint from credentials or a default fallback
+func (cfg *KeyFlowConfig) GetCredentialsTokenEndpoint() string {
+	if cfg.ServiceAccountKey == nil || cfg.ServiceAccountKey.Credentials == nil {
+		return tokenAPI
+	}
+
+	if cfg.ServiceAccountKey.Credentials.TokenEndpoint == "" {
+		return tokenAPI
+	}
+
+	return cfg.ServiceAccountKey.Credentials.TokenEndpoint
+}
+
 func (c *KeyFlow) Init(cfg *KeyFlowConfig) error {
 	// No concurrency at this point, so no mutex check needed
 	c.token = &TokenResponseBody{}
 	c.config = cfg
 
 	if c.config.TokenUrl == "" {
-		c.config.TokenUrl = tokenAPI
+		c.config.TokenUrl = c.config.GetCredentialsTokenEndpoint()
 	}
 
 	c.tokenExpirationLeeway = defaultTokenExpirationLeeway

core/clients/key_flow_test.go

@@ -76,12 +76,14 @@ func TestKeyFlowInit(t *testing.T) {
 		genPrivateKey     bool
 		invalidPrivateKey bool
 		wantErr           bool
+		wantTokenUrl      string
 	}{
 		{
 			name:              "ok-provided-private-key",
 			serviceAccountKey: fixtureServiceAccountKey(),
 			genPrivateKey:     true,
 			wantErr:           false,
+			wantTokenUrl:      tokenAPI,
 		},
 		{
 			name:              "missing_private_key",
@@ -102,6 +104,15 @@ func TestKeyFlowInit(t *testing.T) {
 			invalidPrivateKey: true,
 			wantErr:           true,
 		},
+		{
+			name: "ok-custom-token-endpoint",
+			serviceAccountKey: fixtureServiceAccountKey(func(s *ServiceAccountKeyResponse) {
+				s.Credentials.TokenEndpoint = "https://custom.stackit.cloud/token"
+			}),
+			genPrivateKey: true,
+			wantErr:       false,
+			wantTokenUrl:  "https://custom.stackit.cloud/token",
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -126,6 +137,12 @@ func TestKeyFlowInit(t *testing.T) {
 			if keyFlow.config == nil {
 				t.Error("config is nil")
 			}
+
+			if !tt.wantErr && tt.wantTokenUrl != "" {
+				if keyFlow.config.TokenUrl != tt.wantTokenUrl {
+					t.Errorf("KeyFlow.Init() TokenUrl = %v, wantTokenUrl %v", keyFlow.config.TokenUrl, tt.wantTokenUrl)
+				}
+			}
 		})
 	}
 }