From 8976cdc616afb9778a12406a2c7e7637055668f8 Mon Sep 17 00:00:00 2001
From: Russ Johnson <rujohnso@adobe.com>
Date: Wed, 25 Feb 2026 11:43:13 +0100
Subject: [PATCH 01/11] initial draft of new authentication strategies

---
 .../app_builder_guides/storage/database.md    | 48 ++++++++++++++-----
 1 file changed, 36 insertions(+), 12 deletions(-)

diff --git a/src/pages/guides/app_builder_guides/storage/database.md b/src/pages/guides/app_builder_guides/storage/database.md
index 457a20bcf..833c91151 100644
--- a/src/pages/guides/app_builder_guides/storage/database.md
+++ b/src/pages/guides/app_builder_guides/storage/database.md
@@ -18,6 +18,12 @@ Database Storage for App Builder provides document-style database persistence fo
 
 There is a strict one-to-one relationship between an AIO project workspace and a workspace database, and each workspace database is entirely isolated from all other workspace databases.
 
+## App Builder Data Services API
+
+In order to use App Builder Database Storage in an AIO project workspace you must add the "App Builder Data Services" API. This sets up the necessary authentication between runtime actions and the App Builder Database Storage service itself.
+
+Adding the "App Builder Data Services" API can be done in the developer console like any other API, and does not require any special license or subscription beyond the App Builder license itself.
+
 ## Provisioning a workspace database
 
 Before using Database Storage in an AIO project workspace, a workspace database must be provisioned. This is a self-service operation requiring no special permissions.
@@ -80,6 +86,11 @@ aio plugins:install @adobe/aio-cli-plugin-app@next
 aio plugins:install @adobe/aio-cli-plugin-app-storage@next
 ```
 
+The db pluging for the AIO CLI is included in the latest version of the AIO CLI (TODO verify if this is enough.)
+```bash
+npm install -g @adobe/aio-cli
+```
+
 ### Region selection
 
 When using the DB plugin in the AIO CLI, it is important that the region is the same as where the database is provisioned. If not, the connection will fail.
@@ -288,34 +299,48 @@ The `aio-lib-db` package is intentionally modeled on the [MongoDB Node Driver](h
 npm install @adobe/aio-lib-db
 ```
 
+### Initialization and Authentication
+
+**aio-lib-db** must always be initialized with an IMS Access Token. As long as the "App Builder Data Services" API has been set up, the simplest way to generate a token is by using the **@adobe/aio-sdk** library like so:
+
+```javascript
+const { generateAccessToken } = require('@adobe/aio-sdk').Core.AuthClient;
+async function main(params) {
+  const token = await generateAccessToken(params);
+  const db = await libDb.init({token: token});
+}
+```
+
+The **@adobe/aio-sdk** library transparently manages caching and refreshing tokens as need so there is no need to implement that yourself.
+
 ### Region selection
 
 **aio-lib-db** must be initialized in the region the workspace database was provisioned. Otherwise, the connection will fail.
 
-To explicitly initialize the library in a specific region, pass the `{region: "<region>"}` arguement to the `libDb.init()` method.
+To explicitly initialize the library in a specific region, pass the `{region: "<region>"}` argument to the `libDb.init()` method.
 
-Called with no arguments, `libDb.init()` will initialize the library either in the default `amer` region or in the region defined in the `AIO_DB_REGION` environment variable.
+Called without an explicit region, `libDb.init()` will initialize the library either in the default `amer` region or in the region defined in the `AIO_DB_REGION` environment variable.
 
 ### Basic usage
 
-The following assumes that a Workspace Database has been provisioned in the AIO Project Workspace using the DB Plugin in the AIO CLI as described above.
-
-Connecting to App Builder Database Storage is where `aio-lib-db` most differs from the MongoDB Node Driver.
-
-The following is the general pattern for loading and using `aio-lib-db`:
+The following is the general pattern for initializing and using `aio-lib-db`. It assumes that a Workspace Database has been provisioned in the AIO Project Workspace using the DB Plugin in the AIO CLI as described above.
 
 ```javascript
+const { generateAccessToken } = require('@adobe/aio-sdk').Core.AuthClient;
 const libDb = require('@adobe/aio-lib-db')
 
-async function main() {
+async function main(params) {
   let client
   try {
-
+    
+    // Generate IMS access token
+    const token = await generateAccessToken(params);
+    
     // Implicit region initialization
-    const db = await libDb.init()
+    const db = await libDb.init({token: token})
       
     // Explicit region initialization
-    // const db = await libDb.init({region: "emea"})
+    // const db = await libDb.init({token: token, region: "emea"})
 
     // Set up a connection
     client = await db.connect()
@@ -343,7 +368,6 @@ async function main() {
 
 A few things to note in comparison with the MongoDB Node Driver:
 
-- You do not need to specify connection credentials because they are taken from the runtime context, specifically runtime namespace and auth.
 - You do not need to specify the database URL because all requests go through the App Builder Storage Database Service.
 - The library must be initialized in the same region the database was provisioned in.
 - There is no option to select a different database because there is always a one-to-one relationship between an AIO Project Workspace and Workspace Database.

From 082f6bd74d4c12eaa0a6fe997134d8068405d32a Mon Sep 17 00:00:00 2001
From: Russ Johnson <rujohnso@adobe.com>
Date: Wed, 25 Feb 2026 11:54:44 +0100
Subject: [PATCH 02/11] added missing manifest requirements

---
 .../app_builder_guides/storage/database.md       | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/src/pages/guides/app_builder_guides/storage/database.md b/src/pages/guides/app_builder_guides/storage/database.md
index 833c91151..0b7cbe6ec 100644
--- a/src/pages/guides/app_builder_guides/storage/database.md
+++ b/src/pages/guides/app_builder_guides/storage/database.md
@@ -301,7 +301,7 @@ npm install @adobe/aio-lib-db
 
 ### Initialization and Authentication
 
-**aio-lib-db** must always be initialized with an IMS Access Token. As long as the "App Builder Data Services" API has been set up, the simplest way to generate a token is by using the **@adobe/aio-sdk** library like so:
+**aio-lib-db** must always be initialized with an IMS Access Token. The simplest way to generate a token is by using the **@adobe/aio-sdk** library like so:
 
 ```javascript
 const { generateAccessToken } = require('@adobe/aio-sdk').Core.AuthClient;
@@ -311,6 +311,20 @@ async function main(params) {
 }
 ```
 
+**Important**: for the above code to work in a runtime action, two things must be in place:
+
+- The AIO project workspace must include the "App Builder Data Services" API.
+- The `include-ims-credentials` annotation for the runtime action must be set to `true` in the `app.config.yaml` application manifest.
+
+The `include-ims-credentials` annotation looks something like this:
+```yaml
+actions:
+  action:
+    function: actions/generic/action.js
+    annotations:
+      include-ims-credentials: true
+```
+
 The **@adobe/aio-sdk** library transparently manages caching and refreshing tokens as need so there is no need to implement that yourself.
 
 ### Region selection

From 8c12c9657760b1121d250edfc84eecb17fc05119 Mon Sep 17 00:00:00 2001
From: Russ Johnson <rujohnso@adobe.com>
Date: Wed, 25 Feb 2026 11:58:26 +0100
Subject: [PATCH 03/11] removed update to installation

---
 src/pages/guides/app_builder_guides/storage/database.md | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/src/pages/guides/app_builder_guides/storage/database.md b/src/pages/guides/app_builder_guides/storage/database.md
index 0b7cbe6ec..8bcfc7de7 100644
--- a/src/pages/guides/app_builder_guides/storage/database.md
+++ b/src/pages/guides/app_builder_guides/storage/database.md
@@ -86,11 +86,6 @@ aio plugins:install @adobe/aio-cli-plugin-app@next
 aio plugins:install @adobe/aio-cli-plugin-app-storage@next
 ```
 
-The db pluging for the AIO CLI is included in the latest version of the AIO CLI (TODO verify if this is enough.)
-```bash
-npm install -g @adobe/aio-cli
-```
-
 ### Region selection
 
 When using the DB plugin in the AIO CLI, it is important that the region is the same as where the database is provisioned. If not, the connection will fail.

From 771fa89ce984c7c7c9800c2d51ffbb3086e39260 Mon Sep 17 00:00:00 2001
From: Russ Johnson <rujohnso@adobe.com>
Date: Wed, 4 Mar 2026 14:40:52 +0100
Subject: [PATCH 04/11] corrected code sample

---
 src/pages/guides/app_builder_guides/storage/database.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/pages/guides/app_builder_guides/storage/database.md b/src/pages/guides/app_builder_guides/storage/database.md
index 8bcfc7de7..3b45fbdd0 100644
--- a/src/pages/guides/app_builder_guides/storage/database.md
+++ b/src/pages/guides/app_builder_guides/storage/database.md
@@ -300,6 +300,7 @@ npm install @adobe/aio-lib-db
 
 ```javascript
 const { generateAccessToken } = require('@adobe/aio-sdk').Core.AuthClient;
+const libDb = require('@adobe/aio-lib-db');
 async function main(params) {
   const token = await generateAccessToken(params);
   const db = await libDb.init({token: token});

From 93cd64bb57798f82ceb29179a016d9d878c24f8a Mon Sep 17 00:00:00 2001
From: Russ Johnson <rujohnso@adobe.com>
Date: Thu, 5 Mar 2026 11:43:06 +0100
Subject: [PATCH 05/11] minor fix to code formatting

---
 src/pages/guides/app_builder_guides/storage/database.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/pages/guides/app_builder_guides/storage/database.md b/src/pages/guides/app_builder_guides/storage/database.md
index 3b45fbdd0..fab7887e7 100644
--- a/src/pages/guides/app_builder_guides/storage/database.md
+++ b/src/pages/guides/app_builder_guides/storage/database.md
@@ -299,8 +299,9 @@ npm install @adobe/aio-lib-db
 **aio-lib-db** must always be initialized with an IMS Access Token. The simplest way to generate a token is by using the **@adobe/aio-sdk** library like so:
 
 ```javascript
-const { generateAccessToken } = require('@adobe/aio-sdk').Core.AuthClient;
+const {generateAccessToken} = require('@adobe/aio-sdk').Core.AuthClient;
 const libDb = require('@adobe/aio-lib-db');
+
 async function main(params) {
   const token = await generateAccessToken(params);
   const db = await libDb.init({token: token});
@@ -336,8 +337,8 @@ Called without an explicit region, `libDb.init()` will initialize the library ei
 The following is the general pattern for initializing and using `aio-lib-db`. It assumes that a Workspace Database has been provisioned in the AIO Project Workspace using the DB Plugin in the AIO CLI as described above.
 
 ```javascript
-const { generateAccessToken } = require('@adobe/aio-sdk').Core.AuthClient;
-const libDb = require('@adobe/aio-lib-db')
+const {generateAccessToken} = require('@adobe/aio-sdk').Core.AuthClient;
+const libDb = require('@adobe/aio-lib-db');
 
 async function main(params) {
   let client

From d2e2a1d683931b4706e193e91c5540baea837be3 Mon Sep 17 00:00:00 2001
From: Russ Johnson <rujohnso@adobe.com>
Date: Thu, 5 Mar 2026 15:28:22 +0100
Subject: [PATCH 06/11] reordered navigation config

---
 src/pages/config.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/pages/config.md b/src/pages/config.md
index a872ebb08..3e7fcb315 100644
--- a/src/pages/config.md
+++ b/src/pages/config.md
@@ -90,8 +90,8 @@
                 - [State and Files](guides/app_builder_guides/storage/application-state.md)
                 - [Database (Beta)](guides/app_builder_guides/storage/database.md)
                     - [aio app db Commands](guides/app_builder_guides/storage/db-commands.md)
-                    - [MongoDB Compatibility](guides/app_builder_guides/storage/db-mongo-compatibility.md)
                     - [Runtime Actions](guides/app_builder_guides/storage/db-runtime-actions.md)
+                    - [MongoDB Compatibility](guides/app_builder_guides/storage/db-mongo-compatibility.md)
                     - [Best Practices](guides/app_builder_guides/storage/db-best-practices.md)
             - [Telemetry](guides/app_builder_guides/telemetry.md) 
         - [Runtime Guides](guides/runtime_guides/index.md) 

From 3fc2ccd7840503b4de47ba39d66e1cbfdb55ad5e Mon Sep 17 00:00:00 2001
From: Russ Johnson <rujohnso@adobe.com>
Date: Fri, 6 Mar 2026 10:03:17 +0100
Subject: [PATCH 07/11] Apply suggestions from code review

Co-authored-by: Jared Hoover <98363870+jhadobe@users.noreply.github.com>
---
 .../app_builder_guides/storage/database.md      | 17 +++++++++--------
 .../guides/app_builder_guides/storage/index.md  |  2 +-
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/src/pages/guides/app_builder_guides/storage/database.md b/src/pages/guides/app_builder_guides/storage/database.md
index 0c12a6221..64ba50abd 100644
--- a/src/pages/guides/app_builder_guides/storage/database.md
+++ b/src/pages/guides/app_builder_guides/storage/database.md
@@ -20,9 +20,9 @@ There is a strict one-to-one relationship between an AIO project workspace and a
 
 ## App Builder Data Services API
 
-In order to use App Builder Database Storage in an AIO project workspace you must add the "App Builder Data Services" API. This sets up the necessary authentication between runtime actions and the App Builder Database Storage service itself.
+In order to use App Builder Database Storage in an AIO project workspace, you must add the **App Builder Data Services** API, which provides the necessary authentication between runtime actions and the App Builder Database Storage service.
 
-Adding the "App Builder Data Services" API can be done in the developer console like any other API, and does not require any special license or subscription beyond the App Builder license itself.
+You can add the **App Builder Data Services** API in the developer console like any other API. It does not require any special license or subscription beyond the App Builder license.
 
 ## Provision a workspace database
 
@@ -85,9 +85,9 @@ Run the following command in the root of your AIO project workspace to install t
 npm install @adobe/aio-lib-db
 ```
 
-### Initialization and Authentication
+### Initialization and authentication
 
-**aio-lib-db** must always be initialized with an IMS Access Token. The simplest way to generate a token is by using the **@adobe/aio-sdk** library like so:
+You must always initialize **aio-lib-db** with an IMS Access Token. The simplest way to generate a token is by using the **@adobe/aio-sdk** library as demonstrated in the following example:
 
 ```javascript
 const {generateAccessToken} = require('@adobe/aio-sdk').Core.AuthClient;
@@ -99,12 +99,13 @@ async function main(params) {
 }
 ```
 
-**Important**: for the above code to work in a runtime action, two things must be in place:
+This example has the following requirements:
 
-- The AIO project workspace must include the "App Builder Data Services" API. See [App Builder Data Services API](#usage-quotas-and-limits) for details.
+- The AIO project workspace must include the **App Builder Data Services** API. See [App Builder Data Services API](#usage-quotas-and-limits) for details.
 - The `include-ims-credentials` annotation for the runtime action must be set to `true` in the `app.config.yaml` application manifest.
 
-The `include-ims-credentials` annotation looks something like this:
+The `include-ims-credentials` annotation will look similar to the following example:
+
 ```yaml
 actions:
   action:
@@ -113,7 +114,7 @@ actions:
       include-ims-credentials: true
 ```
 
-The **@adobe/aio-sdk** library transparently manages caching and refreshing tokens as need so there is no need to implement that yourself.
+The **@adobe/aio-sdk** library transparently manages caching and refreshing tokens as needed, so you do not need to implement caching or refreshing tokens yourself.
 
 ### Region selection
 
diff --git a/src/pages/guides/app_builder_guides/storage/index.md b/src/pages/guides/app_builder_guides/storage/index.md
index 5c2dd5a1d..ae3c02370 100644
--- a/src/pages/guides/app_builder_guides/storage/index.md
+++ b/src/pages/guides/app_builder_guides/storage/index.md
@@ -193,4 +193,4 @@ aio app db provision
 
 For State and Files no additional configuration is needed. These libraries automatically use your App Builder credentials for authentication and authorization.
 
-The Database library does require some additional configuration (see [App Builder Data Services API](./database.md#initialization-and-authentication) for details) but does not require any special entitlements beyond App Builder itself.
+The Database library does require some additional configuration, but does not require any special entitlements beyond App Builder itself. See the [App Builder Data Services API](./database.md#initialization-and-authentication) documentation for details.

From 60fb97b5c3f50058511a4535fee8ef53ea89ca9d Mon Sep 17 00:00:00 2001
From: Russ Johnson <rujohnso@adobe.com>
Date: Fri, 6 Mar 2026 10:06:12 +0100
Subject: [PATCH 08/11] indent yaml sample

---
 .../guides/app_builder_guides/storage/database.md      | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/pages/guides/app_builder_guides/storage/database.md b/src/pages/guides/app_builder_guides/storage/database.md
index 64ba50abd..3d6a979b6 100644
--- a/src/pages/guides/app_builder_guides/storage/database.md
+++ b/src/pages/guides/app_builder_guides/storage/database.md
@@ -107,11 +107,11 @@ This example has the following requirements:
 The `include-ims-credentials` annotation will look similar to the following example:
 
 ```yaml
-actions:
-  action:
-    function: actions/generic/action.js
-    annotations:
-      include-ims-credentials: true
+  actions:
+    action:
+      function: actions/generic/action.js
+      annotations:
+        include-ims-credentials: true
 ```
 
 The **@adobe/aio-sdk** library transparently manages caching and refreshing tokens as needed, so you do not need to implement caching or refreshing tokens yourself.

From 7416494eb85f6d276f4669f3caea3d16c49cfce9 Mon Sep 17 00:00:00 2001
From: Russ Johnson <rujohnso@adobe.com>
Date: Fri, 6 Mar 2026 10:11:05 +0100
Subject: [PATCH 09/11] corrected links

---
 src/pages/guides/app_builder_guides/storage/database.md | 2 +-
 src/pages/guides/app_builder_guides/storage/index.md    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/pages/guides/app_builder_guides/storage/database.md b/src/pages/guides/app_builder_guides/storage/database.md
index 3d6a979b6..06a89837e 100644
--- a/src/pages/guides/app_builder_guides/storage/database.md
+++ b/src/pages/guides/app_builder_guides/storage/database.md
@@ -101,7 +101,7 @@ async function main(params) {
 
 This example has the following requirements:
 
-- The AIO project workspace must include the **App Builder Data Services** API. See [App Builder Data Services API](#usage-quotas-and-limits) for details.
+- The AIO project workspace must include the **App Builder Data Services** API. See [App Builder Data Services API](#app-builder-data-services-api) for details.
 - The `include-ims-credentials` annotation for the runtime action must be set to `true` in the `app.config.yaml` application manifest.
 
 The `include-ims-credentials` annotation will look similar to the following example:
diff --git a/src/pages/guides/app_builder_guides/storage/index.md b/src/pages/guides/app_builder_guides/storage/index.md
index ae3c02370..e92868860 100644
--- a/src/pages/guides/app_builder_guides/storage/index.md
+++ b/src/pages/guides/app_builder_guides/storage/index.md
@@ -193,4 +193,4 @@ aio app db provision
 
 For State and Files no additional configuration is needed. These libraries automatically use your App Builder credentials for authentication and authorization.
 
-The Database library does require some additional configuration, but does not require any special entitlements beyond App Builder itself. See the [App Builder Data Services API](./database.md#initialization-and-authentication) documentation for details.
+The Database library does require some additional configuration, but does not require any special entitlements beyond App Builder itself. See the [App Builder Data Services API](./database.md#app-builder-data-services-api) documentation for details.

From 9c8447ec5f0aa8f27389b7405ea37a391dcbed3a Mon Sep 17 00:00:00 2001
From: Russ Johnson <rujohnso@adobe.com>
Date: Fri, 6 Mar 2026 15:45:17 +0100
Subject: [PATCH 10/11] corrected token syntax

---
 src/pages/guides/app_builder_guides/storage/database.md       | 2 +-
 .../guides/app_builder_guides/storage/db-runtime-actions.md   | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/pages/guides/app_builder_guides/storage/database.md b/src/pages/guides/app_builder_guides/storage/database.md
index 06a89837e..1642add48 100644
--- a/src/pages/guides/app_builder_guides/storage/database.md
+++ b/src/pages/guides/app_builder_guides/storage/database.md
@@ -95,7 +95,7 @@ const libDb = require('@adobe/aio-lib-db');
 
 async function main(params) {
   const token = await generateAccessToken(params);
-  const db = await libDb.init({token: token});
+  const db = await libDb.init({token: token.access_token});
 }
 ```
 
diff --git a/src/pages/guides/app_builder_guides/storage/db-runtime-actions.md b/src/pages/guides/app_builder_guides/storage/db-runtime-actions.md
index dcb28d853..31ab6a9d3 100644
--- a/src/pages/guides/app_builder_guides/storage/db-runtime-actions.md
+++ b/src/pages/guides/app_builder_guides/storage/db-runtime-actions.md
@@ -30,10 +30,10 @@ async function main(params) {
     const token = await generateAccessToken(params);
 
     // Implicit region initialization
-    const db = await libDb.init({token: token})
+    const db = await libDb.init({token: token.access_token})
 
     // Explicit region initialization
-    // const db = await libDb.init({token: token, region: "emea"})
+    // const db = await libDb.init({token: token.access_token, region: "emea"})
 
     // Set up a connection
     client = await db.connect()

From 4808d1a48b9044bd86b8b22e45722824bb69147b Mon Sep 17 00:00:00 2001
From: Russ Johnson <rujohnso@adobe.com>
Date: Fri, 6 Mar 2026 15:52:07 +0100
Subject: [PATCH 11/11] plugin version confirmed

---
 src/pages/guides/app_builder_guides/storage/db-commands.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/pages/guides/app_builder_guides/storage/db-commands.md b/src/pages/guides/app_builder_guides/storage/db-commands.md
index e66c4452f..39b87ab5f 100644
--- a/src/pages/guides/app_builder_guides/storage/db-commands.md
+++ b/src/pages/guides/app_builder_guides/storage/db-commands.md
@@ -18,7 +18,7 @@ The following is only a brief introduction to the DB Plugin. For more thorough d
 
 ## Installation
 
-The DB plugin for the AIO CLI requires `@adobe/aio-cli-plugin-app` version 14.5.1 or higher and `@adobe/aio-cli-plugin-app-storage` version 1.3.0 (to be confirmed) or higher.
+The DB plugin for the AIO CLI requires `@adobe/aio-cli-plugin-app` version 14.5.1 or higher and `@adobe/aio-cli-plugin-app-storage` version 1.3.0 or higher.
 
 These are install automatically by updating `@adobe/aio-cli` to the latest version:
 ```bash