diff --git a/apps/headlamp/README.md b/apps/headlamp/README.md
index f5b0a27..aa333d0 100644
--- a/apps/headlamp/README.md
+++ b/apps/headlamp/README.md
@@ -39,4 +39,47 @@ Users authenticate through the Pocket ID SSO and receive cluster-admin permissio
 After deployment via ArgoCD, access the dashboard at:
 https://headlamp.basicstack.de
 
-Users will be redirected to Pocket ID for authentication before accessing the cluster dashboard.
+### Authentication Methods
+
+#### 1. OIDC Authentication (Recommended)
+
+Users will be redirected to Pocket ID for authentication. Once OIDC is fully configured in Pocket ID:
+- Navigate to https://headlamp.basicstack.de
+- Click "Sign in with OIDC"
+- Authenticate via Pocket ID
+- Headlamp uses the `headlamp-admin` ServiceAccount for all Kubernetes API calls
+
+#### 2. Token-Based Authentication (Fallback)
+
+For testing or when OIDC is not available, you can use token-based authentication:
+
+```bash
+# Generate a token from the headlamp-admin ServiceAccount
+kubectl create token headlamp-admin -n headlamp
+
+# Copy the token and paste it in the Headlamp login form
+```
+
+**Important**: The ServiceAccount exists in the `headlamp` namespace, not `kube-system`. Using the wrong namespace will result in 403 errors when accessing Kubernetes APIs.
+
+The token has `cluster-admin` permissions and provides full access to all cluster resources including metrics APIs.
+
+## Troubleshooting
+
+### 403 Errors on Metrics API
+
+If you see 403 errors like `GET https://headlamp.basicstack.de/clusters/main/apis/metrics.k8s.io/v1beta1/nodes`:
+
+**Cause**: Using a token from the wrong namespace or a ServiceAccount without sufficient permissions.
+
+**Solution**: Generate the token from the correct namespace:
+```bash
+kubectl create token headlamp-admin -n headlamp
+```
+
+### Asset Loading Errors
+
+If you encounter errors loading JavaScript assets, check:
+- Ingress configuration is correct
+- TLS certificate is valid
+- Browser console for specific error messages