From 7b7344673042373cc86f99c52fb669160819519d Mon Sep 17 00:00:00 2001
From: Saurabh Kumar Bajpai <saurabhkumarbajpaiai@Saurabhs-MacBook-Air.local>
Date: Tue, 19 May 2026 15:12:15 +0530
Subject: [PATCH] docs: add auth token troubleshooting

---
 README.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/README.md b/README.md
index 74b02c5..04d3c73 100644
--- a/README.md
+++ b/README.md
@@ -325,6 +325,30 @@ apidrift **never stores your actual data** — only the shape (field names + typ
 
 ---
 
+## Troubleshooting
+
+### Authorization header looks empty or unresolved
+
+If apidrift warns that your `Authorization` header looks empty/unresolved, `${STAGING_TOKEN}` or `${PROD_TOKEN}` likely resolved to an empty value before the request was sent. Check that your token names match the placeholders in `apidrift.config.json`.
+
+For bash/zsh:
+
+```bash
+export STAGING_TOKEN="your_token_here"
+export PROD_TOKEN="your_token_here"
+```
+
+For PowerShell:
+
+```powershell
+$env:STAGING_TOKEN = "your_token_here"
+$env:PROD_TOKEN = "your_token_here"
+```
+
+You can also place the variables in a `.env` file in the same directory where you run `apidrift`; this is usually the project root that contains `apidrift.config.json`. Keep `.env` out of git so real tokens are not committed.
+
+---
+
 ## Snapshot Storage
 
 Snapshots are stored globally at `~/.apidrift/snapshots/` — accessible from any project on your machine.