IBM · ricellis · Aug 15, 2025 · Aug 15, 2025 · Aug 15, 2025
@@ -14,6 +14,11 @@ KNOWN_ISSUES.md @IBM/cloudant-sdks
 LICENSE @IBM/cloudant-sdks
 README.md @IBM/cloudant-sdks
 SECURITY.md @IBM/cloudant-sdks
+docs/Authentication.md @IBM/cloudant-sdks
+docs/Changes_Follower.md @IBM/cloudant-sdks
+docs/Examples.md @IBM/cloudant-sdks
+docs/Pagination.md @IBM/cloudant-sdks
+docs/README.md @IBM/cloudant-sdks
 scripts/publish_buildinfo.sh @IBM/cloudant-sdks
 scripts/pydoc/generate-index-html.sh @IBM/cloudant-sdks
 scripts/pydoc/publish-doc.sh @IBM/cloudant-sdks

diff --git a/.secrets.baseline b/.secrets.baseline
@@ -3,7 +3,7 @@
     "files": "^.secrets.baseline$",
     "lines": "(?i)^\\s*\"(?:transaction|x-couch-request|x-request)-id\": \"[^\"]+\",?$|^\\s*\"(?:last_|update_|purge_|checkpointed_source_|source_|through_)?seq\": \"[^\"]+\",?$|^\\s*\"(?:doc_)?id\": \"[^\"]+\",?$|^\\s*\"(?:signature|name|uuid)\": \"[^\"]+\",?$"
   },
-  "generated_at": "2025-07-15T14:37:41Z",
+  "generated_at": "2025-08-15T10:14:15Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -82,17 +82,27 @@
         "hashed_secret": "bb589d0621e5472f470fa3425a234c74b1e202e8",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 309,
+        "line_number": 325,
         "type": "Secret Keyword",
         "verified_result": null
       }
     ],
     "README.md": [
       {
-        "hashed_secret": "32e8612d8ca77c7ea8374aa7918db8e5df9252ed",
+        "hashed_secret": "7740cecbbf3c508248997e0b3b1c24cc00a2759a",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 199,
+        "line_number": 122,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
+    "docs/Authentication.md": [
+      {
+        "hashed_secret": "7740cecbbf3c508248997e0b3b1c24cc00a2759a",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 62,
         "type": "Secret Keyword",
         "verified_result": null
       }

@@ -0,0 +1,161 @@
+# Authentication
+
+
+<details open>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
+- [Authenticators](#authenticators)
+- [Authentication with environment variables](#authentication-with-environment-variables)
+  * [IAM API key authentication](#iam-api-key-authentication)
+  * [IAM Trusted profile (container) authentication](#iam-trusted-profile-container-authentication)
+  * [IAM Trusted profile (VPC) authentication](#iam-trusted-profile-vpc-authentication)
+  * [IAM Trusted profile (assume identity) authentication](#iam-trusted-profile-assume-identity-authentication)
+  * [Session cookie authentication](#session-cookie-authentication)
+  * [Bearer token authentication](#bearer-token-authentication)
+  * [Basic authentication](#basic-authentication)
+- [Authentication with external configuration](#authentication-with-external-configuration)
+- [Programmatic authentication](#programmatic-authentication)
+</details>
+
+## Authenticators
+
+This library requires credentials to authenticate with IBM Cloudant. These credentials may be:
+* IBM Cloud IAM credentials (with authentication types `CONTAINER`, `VPC`, `IAMASSUME` and `IAM`)
+  * [IBM Cloud account](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-managing-access-for-cloudant#introduction-iam-ai) user, service ID or trusted profile credentials
+    that have access granted to the IBM Cloud Cloudant resource instance.
+  * [IBM Cloudant service credentials](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-locating-your-service-credentials) generated by the IBM Cloud Cloudant resource instance.
+* Username and password credentials (with authentication types `COUCHDB_SESSION` and `BASIC`)
+  * [IBM Cloudant service credentials](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-locating-your-service-credentials) generated for an IBM Cloud Cloudant resource instance not configured as `IAM only`.
+  * IBM Cloudant [legacy credentials](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-work-with-your-account#basic-authentication) (username and password) for instances not in IBM Cloud.
+  * IBM Cloudant [legacy API keys](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-work-with-your-account#api-keys).
+
+| Authentication type | Recommended for | `AUTH_TYPE` | Description |
+| --- | --- | --- | --- |
+| IAM Trusted Profiles (compute resource [container](https://github.com/IBM/python-sdk-core/blob/main/Authentication.md#container-authentication)) | Cloudant<BR>(SDK running in IBM Cloud IKS) | `CONTAINER` | Obtains a compute resource (CR) token from the container.<BR>Exchanges the CR token for an IAM `access_token`.<BR>Adds an `Authorization` header to each HTTP request with the `access_token` bearer.<BR>Automatically renews the access token when needed. |
+| IAM Trusted Profiles (compute resource [VPC](https://github.com/IBM/python-sdk-core/blob/main/Authentication.md#vpc-instance-authentication)) | Cloudant<BR>(SDK running in IBM Cloud VPC) | `VPC` | Obtains an identity token from the VPC instance metadata.<BR>Exchanges the identity token for an IAM `access_token`.<BR>Adds an `Authorization` header to each HTTP request with the `access_token` bearer.<BR>Automatically renews the access token when needed. |
+| IAM Trusted Profiles ([assume identity](https://github.com/IBM/python-sdk-core/blob/main/Authentication.md#identity-and-access-management-iam-authentication-grant-type-assume)) | Cloudant | `IAMASSUME` | Exchanges an IAM API key for an IAM `access_token` (same as `IAM` auth type).<BR>Uses that initial token to obtain a second `access_token` from IAM with the assumed identity information.<BR>Adds an `Authorization` header to each HTTP request with the `access_token` bearer.<BR>Automatically renews the access token when needed. |
+| [IAM API key](https://github.com/IBM/python-sdk-core/blob/main/Authentication.md#identity-and-access-management-iam-authentication-grant-type-apikey) | Cloudant | `IAM` | Exchanges an IAM API key for an IAM `access_token`.<BR>Adds an `Authorization` header to each HTTP request with the `access_token` bearer.<BR>Automatically renews the access token when needed. |
+| [Session cookie](#session-cookie-authentication) | [Cloudant](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-work-with-your-account#cookie-authentication)<BR>(legacy credentials & instances without IAM)<BR><BR>[Apache CouchDB](https://docs.couchdb.org/en/stable/api/server/authn.html#cookie-authentication) | `COUCHDB_SESSION` | Exchanges credentials with `/_session` endpoint to retrieve a cookie.<BR>Adds `Cookie` header and content to each HTTP request.<BR>Automatically renews session when needed. |
+| [Bearer token](https://github.com/IBM/python-sdk-core/blob/main/Authentication.md#bearer-token-authentication) | [Apache CouchDB](https://docs.couchdb.org/en/stable/api/server/authn.html#jwt-authentication)<BR>(using JWT authentication) | `BEARERTOKEN` | Adds an `Authorization` header to each HTTP request with the bearer token.<BR>No token management or renewal.<BR>Also compatible with IAM access tokens managed independently of the SDK. |
+| [Basic](https://github.com/IBM/python-sdk-core/blob/main/Authentication.md#basic-authentication) | [Apache CouchDB](https://docs.couchdb.org/en/stable/api/server/authn.html#basic-authentication)<BR>(if cookies are not enabled) | `BASIC` | Adds an `Authorization` header to each HTTP request with the base64 encoded basic credentials. |
+| [None](https://github.com/IBM/python-sdk-core/blob/main/Authentication.md#no-auth-authentication) | - | `NOAUTH` | Note that this authentication type only works for operations against a database allowing access for unauthenticated users. |
+
+The default authentication type for the SDK is `CONTAINER` unless supplying `APIKEY` configuration, which changes the default authentication type to `IAM`.
+
+## Authentication with environment variables
+
+The default service name is `CLOUDANT` so these examples use `CLOUDANT_` prefixed names.
+
+Any custom service name prefix is valid, provided it matches the name used to instantiate the SDK client
+and applied to all configuration options.
+
+### IAM API key authentication
+
+For Cloudant *IAM API key authentication*, set the following environmental variables by
+amending the values with your own
+[service credentials](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-locating-your-service-credentials). There is no need to set
+`CLOUDANT_AUTH_TYPE` to `IAM` because it is the default when supplying an `APIKEY`.
+
+```sh
+CLOUDANT_URL=https://~replaceWithYourUniqueHost~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
+CLOUDANT_APIKEY=a1b2c3d4e5f6f1g4h7j3k6l9m2p5q8s1t4v7x0z3 # use your own IAM API key
+```
+
+### IAM Trusted profile (container) authentication
+
+For Cloudant *IAM Trusted profile compute resource container authentication*, set the following environmental variables,
+amending with your own correct values. There is no need to set
+`CLOUDANT_AUTH_TYPE` to `CONTAINER` because it is the default.
+
+```sh
+CLOUDANT_URL=https://~replaceWithYourUniqueHost~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
+CLOUDANT_IAM_PROFILE_ID=iam-Profile-00000000-aaaa-4444-bbbb-0123456789ab # use your own IAM profile ID
+```
+
+Alternatives to `CLOUDANT_IAM_PROFILE_ID`:
+* `CLOUDANT_IAM_PROFILE_NAME`
+
+### IAM Trusted profile (VPC) authentication
+
+For Cloudant *IAM Trusted profile compute resource vpc authentication*, set the following environmental variables,
+amending with your own correct values.
+
+```sh
+CLOUDANT_AUTH_TYPE=VPC
+CLOUDANT_URL=https://~replaceWithYourUniqueHost~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
+CLOUDANT_IAM_PROFILE_ID=iam-Profile-00000000-aaaa-4444-bbbb-0123456789ab # use your own IAM profile ID
+```
+
+Alternatives to `CLOUDANT_IAM_PROFILE_ID`:
+* `CLOUDANT_IAM_PROFILE_CRN`
+* No profile information (uses the default trusted profile linked to the compute resource)
+
+### IAM Trusted profile (assume identity) authentication
+
+For Cloudant *IAM Trusted profile assume authentication*, set the following environmental variables,
+amending with your own correct values.
+
+```sh
+CLOUDANT_AUTH_TYPE=IAMASSUME
+CLOUDANT_URL=https://~replaceWithYourUniqueHost~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
+CLOUDANT_IAM_PROFILE_ID=iam-Profile-00000000-aaaa-4444-bbbb-0123456789ab # use your own IAM profile ID
+```
+
+Alternatives to `CLOUDANT_IAM_PROFILE_ID`:
+* `CLOUDANT_IAM_PROFILE_CRN`
+* `CLOUDANT_IAM_PROFILE_NAME` *and* `CLOUDANT_IAM_ACCOUNT_ID` (ID of the account that contains the named trusted profile)
+
+### Session cookie authentication
+
+For `COUCHDB_SESSION` authentication, set the following environmental variables
+amending with your own [service credentials](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-locating-your-service-credentials).
+
+```sh
+CLOUDANT_AUTH_TYPE=COUCHDB_SESSION
+CLOUDANT_URL=https://~replaceWithYourUniqueHost~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
+CLOUDANT_USERNAME=username # replace with your Cloudant legacy username
+CLOUDANT_PASSWORD=password # replace with your Cloudant legacy password or API key (not IAM)
+```
+
+### Bearer token authentication
+
+Preferably use IAM authentication methods to automatically manage bearer tokens.
+
+For *bearer token authentication*, set the following environmental variables,
+amending with your own correct values.
+
+```sh
+CLOUDANT_AUTH_TYPE=BEARERTOKEN
+CLOUDANT_URL=https://~replaceWithYourUniqueHost~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
+CLOUDANT_BEARER_TOKEN=A1b2C3QiOiIyMDE4MDgxNDAwMDAwMDAwMDAwMDBjNzYwNzY2YjYxYjYwYjYwIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyQGdtYWlsLmNvbSIsImF1ZCI6Imh0dHBzOi8vaWF1LmNsb3VkLmlibS5jb20iLCJpYXQiOjE2ODg4ODg4ODgsImV4cCI6MTY4ODg5MjQ4OCwiaXNzIjoiaHR0cHM6Ly9pYXUuY2xvdWQuaWJtLmNvbSIsInNjb3BlIjpbImNsb3VkLnJlYWRlciJdfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c # replace with your bearer token
+```
+
+### Basic authentication
+
+Preferably use [session cookie authentication](#session-cookie-authentication) instead.
+
+To use *basic HTTP authentication* set the following environmental variables,
+amending with your own correct values.
+
+```sh
+CLOUDANT_AUTH_TYPE=BASIC
+CLOUDANT_URL=https://~replaceWithYourUniqueHost~.cloudantnosqldb.appdomain.cloud # use your own Cloudant public or private URL
+CLOUDANT_USERNAME=username # replace with your Cloudant legacy username
+CLOUDANT_PASSWORD=password # replace with your Cloudant legacy password or API key (not IAM)
+```
+
+## Authentication with external configuration
+
+For more information about using an external configuration file, see the related documentation in
+[Cloudant API docs](https://cloud.ibm.com/apidocs/cloudant?code=python#authentication-with-external-configuration),
+or the
+[general SDK usage information](https://github.com/IBM/ibm-cloud-sdk-common#using-external-configuration).
+
+## Programmatic authentication
+
+To learn more about how to use programmatic authentication, see the related
+documentation in the
+[Cloudant API docs](https://cloud.ibm.com/apidocs/cloudant?code=python#programmatic-authentication)
+or in the
+[Python SDK Core document](https://github.com/IBM/python-sdk-core/blob/main/Authentication.md) about authentication.