doc: DOCSP-54251 & DOCSP-54252 -- Document how to move from or to Service Accounts authentication

docs/guides/migrate-to-service-accounts-authentication-guide.md

@@ -0,0 +1,60 @@
+---
+page_title: "Migration Guide: Service Accounts Authentication"
+---
+
+# Migration Guide: Service Accounts Authentication
+
+This guide helps you migrate from Programmatic Access Key (PAK) authentication to Service
+Accounts (SA) authentication and viceversa without impacting your deployment.
+
+**Note:** For more information on SA, see [Service Accounts Overview](https://www.mongodb.com/docs/atlas/api/service-accounts-overview/)
+in the MongoDB documentation.
+
+## Procedure
+
+To migrate from Programmatic Access Key (PAK) authentication to Service
+Accounts (SA) authentication, change your provider declaration variables. You can implement
+this change by either:
+
+- Providing a client ID and secret
+
+- Providing a valid access token
+
+### Provide a Client ID and Secret
+
+The following example shows the variables for PAK authentication:
+
+```terraform
+provider "mongodbatlas" {
+public_key = var.mongodbatlas_public_key
+private_key = var.mongodbatlas_private_key
+}
+```
+
+To change to SA, declare the `client_id` and `client_secret` variables as in the following example:
+
+```terraform
+provider "mongodbatlas" {
+client_id = var.mongodbatlas_client_id
+client_secret = var.mongodbatlas_client_secret
+}
+```
+
+### Provide a Valid Access Token
+
+The following example shows SA authentication set up through the ``access_token`` attribute:
+
+```terraform
+provider "mongodbatlas" { 
+access_token = var.mongodbatlas_access_token
+[is_mongodbgov_cloud = true // optional]
+}
+```
+
+Consider that the access token is **valid for one hour only**.
+
+See [Generate Service Account Token](https://www.mongodb.com/docs/atlas/api/service-accounts/generate-oauth2-token/#std-label-generate-oauth2-token-atlas) for more details on creating an SA token. 
+
+**IMPORTANT:**  Currently, the MongoDB Terraform provider does not support additional Token OAuth features.
+
+**NOTE:** You can't use ``mongodbatlas_event_trigger`` with Service Accounts as the authentication method.

docs/index.md

@@ -12,10 +12,9 @@ See [CHANGELOG](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/
 ```terraform
 # Configure the MongoDB Atlas Provider 
 provider "mongodbatlas" {
-  public_key = var.mongodbatlas_public_key
-  private_key  = var.mongodbatlas_private_key
+client_id = var.mongodbatlas_client_id
+client_secret = var.mongodbatlas_client_secret
 }
-# Create the resources
 ```
 
 ### Provider and terraform version constraints
@@ -50,6 +49,32 @@ Also see [`Atlas for Government Considerations`](https://www.mongodb.com/docs/at
 The MongoDB Atlas provider offers a flexible means of providing credentials for authentication.
 You can use any the following methods:
 
+### Service Accounts
+
+Service Accounts (SA) is the preferred authentication method for the MongoDB Atlas provider.
+The [MongoDB Atlas documentation](https://www.mongodb.com/docs/atlas/configure-api-access/#grant-programmatic-access-to-an-organization) contains the most up-to-date instructions for creating your organization's SA and granting the required access.
+
+To set up SA authentication, provide your credentials as in the following example:
+
+```terraform
+provider "mongodbatlas" {
+client_id = var.mongodbatlas_client_id
+client_secret = var.mongodbatlas_client_secret
+}
+```
+
+Alternatively, you use an access token (valid for only one hour) as in the following example:
+
+```terraform
+provider "mongodbatlas" { 
+access_token = var.mongodbatlas_access_token
+[is_mongodbgov_cloud = true // optional]
+}
+```
+
+See [Migration Guide: Service Accounts Authentication](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/migrate-to-service-accounts-authentication-guide) for more
+details on setting up SA authentication.
+
 ### Environment Variables
 
 You can also provide your credentials via the environment variables,