From b4b4ec2bedd69ab1bfe15d9669942a0ecb2c245e Mon Sep 17 00:00:00 2001
From: Marco Antonio Gil <marco.gil@multisafepay.com>
Date: Thu, 30 Apr 2026 09:24:01 +0200
Subject: [PATCH] PTHMINT-121: Add scoped credential docs and env vars

Add new environment variables to .env.example for terminal/group and cloud POS testing (TERMINAL_GROUP_API_KEY_GROUP_DEFAULT, CLOUD_POS_TERMINAL_GROUP_ID, CLOUD_POS_TERMINAL_ID, CLOUD_POS_ORDER_ID, POS_ORDER_ID, E2E_TERMINAL_GROUP_API_KEY_GROUP_DEFAULT, E2E_CLOUD_POS_TERMINAL_ID). Update README with a new "Initialize with scoped credentials" section showing how to use ScopedCredentialResolver (making api_key optional) and providing a code example for per-scope API key resolution.
---
 .env.example |  7 +++++++
 README.md    | 23 +++++++++++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/.env.example b/.env.example
index 7a2af63..f51301e 100644
--- a/.env.example
+++ b/.env.example
@@ -1,3 +1,10 @@
 API_KEY=
+TERMINAL_GROUP_API_KEY_GROUP_DEFAULT=
+CLOUD_POS_TERMINAL_GROUP_ID=Default
+CLOUD_POS_TERMINAL_ID=
+CLOUD_POS_ORDER_ID=
+POS_ORDER_ID=
 E2E_API_KEY=
 E2E_BASE_URL=https://testapi.multisafepay.com/v1/
+E2E_TERMINAL_GROUP_API_KEY_GROUP_DEFAULT=
+E2E_CLOUD_POS_TERMINAL_ID=
diff --git a/README.md b/README.md
index e30a317..b59392f 100644
--- a/README.md
+++ b/README.md
@@ -75,6 +75,29 @@ from multisafepay import Sdk
 multisafepay_sdk: Sdk = Sdk(api_key='<api_key>', is_production=True)
 ```
 
+### Initialize with scoped credentials
+
+Use `ScopedCredentialResolver` when the API key must change per auth scope.
+When `credential_resolver` is provided, `api_key` becomes optional.
+
+```python
+from multisafepay import Sdk
+from multisafepay.client import ScopedCredentialResolver
+
+
+credential_resolver = ScopedCredentialResolver(
+    default_api_key="<default_api_key>",
+    terminal_group_api_keys={
+        "Default": "<terminal_group_api_key>",
+    },
+)
+
+sdk = Sdk(
+    is_production=False,
+    credential_resolver=credential_resolver,
+)
+```
+
 ### Development-only custom base URL override
 
 By default, the SDK only targets: