diff --git a/docs/api-docs/api-reference/introduction.mdx b/docs/api-docs/api-reference/introduction.mdx
index 607e9d81..831c5976 100644
--- a/docs/api-docs/api-reference/introduction.mdx
+++ b/docs/api-docs/api-reference/introduction.mdx
@@ -22,13 +22,19 @@ https://api.terminal49.com/v2
 
 ## Authentication
 
-Include your API key in the `Authorization` header, prefixed with `Token`:
+Include your API key in the `Authorization` header, prefixed with `Token` (not `Bearer`):
 
 ```bash
 curl https://api.terminal49.com/v2/shipments \
   -H "Authorization: Token YOUR_API_KEY"
 ```
 
+Replace `YOUR_API_KEY` with the raw key value from the [developer portal](https://app.terminal49.com/developers/api-keys) — no quotes, no `Bearer` prefix, and no extra whitespace. A `401 Unauthorized` response with `"Terminal49 API key could not be verified"` means the key is missing, malformed, revoked, or truncated when it was copied.
+
+<Warning>
+  The full API key value is only shown once, right after you create it. Copy the complete token from that screen and store it in a secret manager before navigating away — after that, the value is masked and cannot be revealed again. If you lost the full value, create a new key, copy it immediately, then delete the older key.
+</Warning>
+
 ## Request and response format
 
 - The API follows the [JSON:API](https://jsonapi.org/) specification
diff --git a/docs/api-docs/getting-started/start-here.mdx b/docs/api-docs/getting-started/start-here.mdx
index e23d8c75..7c39bb7c 100644
--- a/docs/api-docs/getting-started/start-here.mdx
+++ b/docs/api-docs/getting-started/start-here.mdx
@@ -38,6 +38,12 @@ You can use any HTTP client. [Postman](https://www.postman.com/) is useful for a
 
 Sign in to your Terminal49 account and go to the [developer portal](https://app.terminal49.com/developers/api-keys) to get your API key.
 
+<Warning>
+  The full API key value is only shown once, right after you create it. Copy the complete token from that screen and store it somewhere safe (for example, a password manager or your deployment's secret manager) before you navigate away. Once you leave the page, the key is masked and cannot be revealed again.
+
+  If you did not capture the full value, create a new key and copy it immediately. You can then delete the older key from the [developer portal](https://app.terminal49.com/developers/api-keys).
+</Warning>
+
 ## Send the Authorization header
 
 The API uses a Token-prefixed API key in the `Authorization` header. Send it with every request: