apply feedback

Signed-off-by: Jorge Turrado <[email protected]>

Author: JorTurFer

README.md

@@ -105,13 +105,20 @@ To authenticate with the SDK, you need a [service account](https://docs.stackit.
 
 The SDK supports two authentication methods:
 
-1. **Key Flow** (Recommended)
+1. **Workload Identity Federation Flow** (Recommended)
+
+   - Uses OIDC trusted tokens
+   - Provides best security through short-lived tokens without secrets
+
+> NOTE: This flow isn't publicly available yet. It'll be public during Q1 2026
+
+2. **Key Flow** (Recommended)
 
    - Uses RSA key-pair based authentication
    - Provides better security through short-lived tokens
    - Supports both STACKIT-generated and custom key pairs
 
-2. **Token Flow**
+3. **Token Flow**
    - Uses long-lived service account tokens
    - Simpler but less secure
 
@@ -120,10 +127,42 @@ The SDK supports two authentication methods:
 The SDK searches for credentials in the following order:
 
 1. Explicit configuration in code
-2. Environment variables (KEY_PATH for KEY)
+2. Environment variables
 3. Credentials file (`$HOME/.stackit/credentials.json`)
 
-For each authentication method, the key flow is attempted first, followed by the token flow.
+For each authentication method, the try order is:
+1. Workload Identity Federation Flow
+2. Key Flow
+3. Token Flow
+
+### Using the Workload Identity Fedearion Flow
+
+1. Create a service account trusted relation in the STACKIT Portal:
+
+   - Navigate to `Service Accounts` → Select account → `Federated Identity Providers` → Add a Federated Identity Provider
+   - Configure the trusted issuer and the required assertions to trust in. (Link to official docs here after GA)
+
+2. Configure authentication using any of these methods:
+
+   **A. Code Configuration**
+
+   ```go
+   // Using wokload identity federation flow
+   config.WithWorkloadIdentityFederationAuth()
+   // With the custom path for the external OIDC token
+   config.WithWorkloadIdentityFederationTokenPath("/path/to/your/federated/token")
+   // For the service account
+   config.WithServiceAccountEmail("[email protected]")
+   ```
+
+   **B. Environment Variables**
+
+   ```bash
+   # With the custom path for the external OIDC token
+   STACKIT_FEDERATED_TOKEN_FILE=/path/to/your/federated/token
+   # For the service account
+   [email protected]
+   ```
 
 ### Using the Key Flow
 

examples/authentication/authentication.go

@@ -72,27 +72,6 @@ func main() {
 		fmt.Printf("[DNS API] Number of zones: %v\n", len(*getZoneResp.Zones))
 	}
 
-	// Create a new API client, that will authenticate using the wif flow
-	// You need to create a service account key and configure the federate identity provider,
-	// then you can init the SDK using default env var
-	os.Setenv("STACKIT_SERVICE_ACCOUNT_EMAIL", "[email protected]")
-	os.Setenv("STACKIT_FEDERATED_TOKEN_FILE", "/path/to/your/federated/token") // Default "/var/run/secrets/stackit.cloud/serviceaccount/token"
-	os.Setenv("STACKIT_IDP_ENDPOINT", "custom token endpoint")                 // Default "https://accounts.stackit.cloud/oauth/v2/token"
-	dnsClient, err = dns.NewAPIClient()
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "[DNS API] Creating API client: %v\n", err)
-		os.Exit(1)
-	}
-
-	// Check that you can make an authenticated request
-	getZoneResp, err = dnsClient.ListZones(context.Background(), projectId).Execute()
-
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "[DNS API] Error when calling `ZoneApi.GetZones`: %v\n", err)
-	} else {
-		fmt.Printf("[DNS API] Number of zones: %v\n", len(*getZoneResp.Zones))
-	}
-
 	// Create a new API client, that will authenticate using the wif flow
 	// You need to create a service account key and configure the federate identity provider,
 	// then you can init the SDK setting fields