doc: Migration guide to move from API Keys (PAKs) to Service Accounts #4047

filipcirtog · 2026-01-08T12:20:53Z

Description

The guide should follows the following steps:

Initial state with PAK resources (org PAK + assignment to project + access list entry)
Intermediate state with both PAK resources and SA resources (org SA + assignment to project + access list entry)
Final state with removed PAK resources, SA resources only.

Link to any related issue(s):

Type of change:

Bug fix (non-breaking change which fixes an issue). Please, add the "bug" label to the PR.
New feature (non-breaking change which adds functionality). Please, add the "enhancement" label to the PR. A migration guide must be created or updated if the new feature will go in a major version.
Breaking change (fix or feature that would cause existing functionality to not work as expected). Please, add the "breaking change" label to the PR. A migration guide must be created or updated.
This change requires a documentation update
Documentation fix/enhancement

Required Checklist:

I have signed the MongoDB CLA
I have read the contributing guides
I have checked that this change does not generate any credentials and that they are NOT accidentally logged anywhere.
I have added tests that prove my fix is effective or that my feature works per HashiCorp requirements
I have added any necessary documentation (if appropriate)
I have run make fmt and formatted my code
If changes include deprecations or removals I have added appropriate changelog entries.
If changes include removal or addition of 3rd party GitHub actions, I updated our internal document. Reach out to the APIx Integration slack channel to get access to the internal document.

Further comments

manupedrozo

Good first draft!

Extra comments:

Did you follow the guide yourself to verify it works as expected?
It would be great to have supporting examples (for both org and project resources) like: migrate_atlas_user_and_atlas_users
- Note the v1/v2/v3 structure that matches this guide
- Then link to the examples guides from the tf docs

manupedrozo · 2026-01-08T12:51:59Z

docs/guides/migrate-pak-to-service-account.md

+page_title: "Migration Guide: Programmatic API Keys (PAKs) to Service Accounts (SAs)"
+---
+
+**Note:** Migration to Service Accounts is **not required**. If you are currently using `mongodbatlas_api_key`, `mongodbatlas_api_key_project_assignment`, and `mongodbatlas_access_list_api_key` resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security, flexibility, or best practices, but existing PAK configurations will continue to work and are supported.


Not sure if flexibility is a pro of SAs vs PAKs.

Suggested change

**Note:** Migration to Service Accounts is **not required**. If you are currently using `mongodbatlas_api_key`, `mongodbatlas_api_key_project_assignment`, and `mongodbatlas_access_list_api_key` resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security, flexibility, or best practices, but existing PAK configurations will continue to work and are supported.

**Note:** Migration to Service Accounts is **not required**. If you are currently using API Key resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security or best practices, but existing PAK configurations will continue to work and are supported.

manupedrozo · 2026-01-08T13:03:42Z

docs/guides/migrate-pak-to-service-account.md

+
+# Migration Guide: Programmatic API Keys (PAKs) to Service Accounts (SAs)
+
+The goal of this guide is to help users transition from Programmatic API Keys (PAKs) to Service Accounts (SAs) in MongoDB Atlas. Service Accounts provide a more secure and flexible authentication method that eliminates the need to manage API key secrets in Terraform state.


"Service Accounts provide a more secure and flexible authentication method" - Not sure how SAs are more flexible
"Service Accounts provide a more secure and flexible authentication method that eliminates the need to manage API key secrets in Terraform state" - But we now have to manage SAs instead of PAKs, so wouldn't include this as an upside.

Take a look at the docs for the advantage of SAs over PAKs: Service accounts are the recommended method to manage authentication to the Atlas Administration API. Service accounts provide improved security over API keys by using the industry standard OAuth 2.0 protocol with the Client Credentials flow.

manupedrozo · 2026-01-08T13:08:03Z

docs/guides/migrate-pak-to-service-account.md

+
+The following table shows the mapping between PAK resources and their Service Account equivalents:
+
+| PAK Resource | Service Account Resource | Notes |


I think we should:

Include project level resources here as well.

Introduce 2 guides (2 sections in this same guide), 1 for org level and 1 for project level. Similar to Org Membership / Team Membership / etc in https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/atlas-user-management

We need to be clear that the project resources should only be used if the user does not have org level permissions to manage service accounts. Otherwise, org level resources are the recommended approach.

manupedrozo · 2026-01-08T13:08:20Z

docs/guides/migrate-pak-to-service-account.md

+
+| PAK Resource | Service Account Resource | Notes |
+|--------------|-------------------------|-------|
+| `mongodbatlas_api_key` | `mongodbatlas_service_account` | Organization-level key/account |


manupedrozo · 2026-01-08T13:11:22Z

docs/guides/migrate-pak-to-service-account.md

+resource "mongodbatlas_api_key_project_assignment" "example" {
+  project_id = var.project_id
+  api_key_id = mongodbatlas_api_key.example.api_key_id
+  roles      = ["GROUP_OWNER", "GROUP_DATA_ACCESS_ADMIN"]


Just for clarity, wouldn't mix GROUP_OWNER with other roles since owner already contains other roles. Maybe go with ["GROUP_READ_ONLY", "GROUP_DATA_ACCESS_READ_ONLY"].

manupedrozo · 2026-01-08T13:12:48Z

docs/guides/migrate-pak-to-service-account.md

+resource "mongodbatlas_access_list_api_key" "example" {
+  org_id     = var.org_id
+  api_key_id = mongodbatlas_api_key.example.api_key_id
+  cidr_block = "192.168.1.0/24"


Matching the alternative to avoid confusion (also in other occurrences)

Suggested change

cidr_block = "192.168.1.0/24"

cidr_block = "192.168.1.100/32"

manupedrozo · 2026-01-08T13:14:00Z

docs/guides/migrate-pak-to-service-account.md

+
+## Stage 2: Intermediate State (Both PAK and SA Resources)
+
+In this stage, you'll add Service Account resources alongside your existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.


Suggested change

In this stage, you'll add Service Account resources alongside your existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.

In this stage, you will add Service Account resources alongside your existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.

manupedrozo · 2026-01-08T13:29:48Z

docs/guides/migrate-pak-to-service-account.md

+
+4. Run `terraform plan` to review the changes.
+5. Run `terraform apply` to create the Service Account resources.
+6. **Important**: Save the Service Account secret from the output. When a Service Account is created, a secret is automatically generated. The secret value is only returned once at creation time.


The output block should be added together with the service account before running apply in step 4

I think we can remove the datasources

manupedrozo

Thanks for the iteration, I think its in much better shape now!
Left more comments - Its ready to share with the docs team as well.

manupedrozo · 2026-01-09T15:33:58Z

docs/guides/migrate-pak-to-service-account.md

+## Overview
+
+Service Accounts are the recommended method to manage authentication to the Atlas Administration API. Service Accounts provide improved security over API keys by using the industry standard OAuth 2.0 protocol with the Client Credentials flow. This guide covers migrating from Programmatic API Keys (PAKs) to Service Accounts (SAs) in MongoDB Atlas.
+
+**Note:** Migration to Service Accounts is **not required**. If you are currently using API Key resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security or best practices, but existing PAK configurations will continue to work and are supported.
+


Suggesting the following. Would like to get docs team input here:

Suggested change

## Overview

Service Accounts are the recommended method to manage authentication to the Atlas Administration API. Service Accounts provide improved security over API keys by using the industry standard OAuth 2.0 protocol with the Client Credentials flow. This guide covers migrating from Programmatic API Keys (PAKs) to Service Accounts (SAs) in MongoDB Atlas.

**Note:** Migration to Service Accounts is **not required**. If you are currently using API Key resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security or best practices, but existing PAK configurations will continue to work and are supported.

## Overview

This guide explains how to migrate from Programmatic API Key (PAK) resources to Service Account (SA) resources.

**Note:** Migration to Service Accounts is **not required**. If you are currently using API Key resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security or best practices, but existing PAK configurations will continue to work and be supported.

manupedrozo · 2026-01-09T15:49:31Z

docs/guides/migrate-pak-to-service-account.md

+
+| PAK Resource | Service Account Resource | Notes |
+|--------------|-------------------------|-------|
+| `mongodbatlas_api_key` | `mongodbatlas_service_account` | Organization-level API key / Service Account |


manupedrozo · 2026-01-09T15:53:48Z

docs/guides/migrate-pak-to-service-account.md

+
+### Step 1: Initial State - PAK Resources Only
+
+This is your starting configuration with organization-level PAK resources (org PAK + assignment to project + access list entry):


Suggested change

This is your starting configuration with organization-level PAK resources (org PAK + assignment to project + access list entry):

Original configuration with organization-level PAK resources:

manupedrozo · 2026-01-09T15:55:21Z

docs/guides/migrate-pak-to-service-account.md

+
+For complete working examples, see the [organization-level migration example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_pak_to_service_account/org_level).
+
+### Step 1: Initial State - PAK Resources Only


Suggested change

### Step 1: Initial State - PAK Resources Only

### Step 1: Initial Configuration - PAK Resources Only

manupedrozo · 2026-01-09T15:56:42Z

docs/guides/migrate-pak-to-service-account.md

+This is your starting configuration with organization-level PAK resources (org PAK + assignment to project + access list entry):
+
+```terraform
+# Organization-level Programmatic API Key


I think we can avoid repeating "organization-level" so often. Should be clear since we are in the "Organization-Level API Keys to Service Accounts" section.

Changing the api key description to not say "for project access" may help.

manupedrozo · 2026-01-09T16:22:56Z

docs/guides/migrate-pak-to-service-account.md

+
+---
+
+- **Important:** The Service Account secret is only returned once at creation time. Make sure to save it securely before proceeding.


Bit out of place, I think you can remove

manupedrozo · 2026-01-09T16:23:55Z

docs/guides/migrate-pak-to-service-account.md

+<details>
+  <summary><span style="font-size:1.4em; font-weight:bold;">Project-Level Migration</span></summary>
+
+## Project-Level API Keys to Service Accounts


Assume same comments as for Org-level steps

manupedrozo · 2026-01-09T16:32:48Z

examples/migrate_pak_to_service_account/org_level/v1/versions.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_version = ">= 1.7.0"


Need TF 1.7?

manupedrozo · 2026-01-09T16:34:17Z

examples/migrate_pak_to_service_account/org_level/v2/outputs.tf

+  description = "The secret value of the first secret created with the service account. Only available after initial creation."
+  value       = try(mongodbatlas_service_account.example.secrets[0].secret, null)
+  sensitive   = true
+}


Suggested change

}

}

manupedrozo · 2026-01-09T16:36:29Z

examples/migrate_pak_to_service_account/org_level/README.md

@@ -0,0 +1,19 @@
+# Combined Example: Organization-Level PAK → Service Account


Given that we don't have readmes with instructions in the subfolders, I suggest following this style of readme here instead: examples/migrate_atlas_user_and_atlas_users/README.md

add migration guide

6673a65

filipcirtog changed the base branch from master to CLOUDP-352932-service-accounts-dev January 8, 2026 12:21

filipcirtog changed the title ~~doc: PAK's to SA migration guide~~ doc: Migration guide to move from API Keys (PAKs) to Service Accounts Jan 8, 2026

manupedrozo reviewed Jan 8, 2026

View reviewed changes

filipcirtog added 3 commits January 9, 2026 15:22

refactoring + examples

abbcbc5

remove boilerplate text

d861ec5

nit: ensure consistency between the org and project guides

f71aec5

manupedrozo reviewed Jan 9, 2026

View reviewed changes


		# Migration Guide: Programmatic API Keys (PAKs) to Service Accounts (SAs)

		The goal of this guide is to help users transition from Programmatic API Keys (PAKs) to Service Accounts (SAs) in MongoDB Atlas. Service Accounts provide a more secure and flexible authentication method that eliminates the need to manage API key secrets in Terraform state.


		The following table shows the mapping between PAK resources and their Service Account equivalents:

		\| PAK Resource \| Service Account Resource \| Notes \|

	\| `mongodbatlas_api_key` \| `mongodbatlas_service_account` \| Organization-level key/account \|
	\| `mongodbatlas_api_key` \| `mongodbatlas_service_account` \| API key / Service Account \|

	cidr_block = "192.168.1.0/24"
	cidr_block = "192.168.1.100/32"


		## Stage 2: Intermediate State (Both PAK and SA Resources)

		In this stage, you'll add Service Account resources alongside your existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.

	In this stage, you'll add Service Account resources alongside your existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.
	In this stage, you will add Service Account resources alongside your existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.


		### Step 1: Initial State - PAK Resources Only

		This is your starting configuration with organization-level PAK resources (org PAK + assignment to project + access list entry):

	This is your starting configuration with organization-level PAK resources (org PAK + assignment to project + access list entry):
	Original configuration with organization-level PAK resources:


		For complete working examples, see the [organization-level migration example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_pak_to_service_account/org_level).

		### Step 1: Initial State - PAK Resources Only

	### Step 1: Initial State - PAK Resources Only
	### Step 1: Initial Configuration - PAK Resources Only


		---

		- Important: The Service Account secret is only returned once at creation time. Make sure to save it securely before proceeding.

		@@ -0,0 +1,19 @@
		# Combined Example: Organization-Level PAK → Service Account

doc: Migration guide to move from API Keys (PAKs) to Service Accounts #4047

Are you sure you want to change the base?

doc: Migration guide to move from API Keys (PAKs) to Service Accounts #4047

Uh oh!

Conversation

filipcirtog commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change:

Required Checklist:

Further comments

Uh oh!

manupedrozo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manupedrozo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

filipcirtog commented Jan 8, 2026 •

edited

Loading