---
page_title: "Migration Guide: Programmatic API Keys (PAKs) to Service Accounts (SAs)"
---
# Migration Guide: Programmatic API Keys (PAKs) to Service Accounts (SAs)
## Overview
This guide explains how to migrate from Programmatic API Key (PAK) resources to Service Account (SA) resources managed by Terraform.
**Important:** The steps in this guide are for migrating Terraform-managed PAK and SA resources (e.g., `mongodbatlas_api_key`, `mongodbatlas_service_account`). If you are looking to change the Terraform provider authentication method from PAK to SA, refer to the [Provider Configuration guide](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/provider-configuration).
**Note:** Migration to Service Accounts is recommended but **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.
## Before You Begin
- **Backup your Terraform state file** before making any changes.
- **Test the process in a non-production environment** if possible.
- Managing Service Accounts with Terraform **exposes sensitive organizational secrets** in Terraform's state. We suggest following [Terraform's best practices](https://developer.hashicorp.com/terraform/language/state/sensitive-data).
---
Organization-Level Migration
## Organization-Level API Keys to Service Accounts
**Objective**: Migrate from organization-level PAK resources (`mongodbatlas_api_key`, `mongodbatlas_api_key_project_assignment`, `mongodbatlas_access_list_api_key`) to organization-level Service Account resources (`mongodbatlas_service_account`, `mongodbatlas_service_account_project_assignment`, `mongodbatlas_service_account_access_list_entry`).
### Resource Mapping
The following table shows the mapping between organization-level PAK resources and their Service Account equivalents:
| PAK Resource | Service Account Resource | Notes |
|--------------|-------------------------|-------|
| `mongodbatlas_api_key` | `mongodbatlas_service_account` | API key / Service Account |
| `mongodbatlas_api_key_project_assignment` | `mongodbatlas_service_account_project_assignment` | Project assignment |
| `mongodbatlas_access_list_api_key` | `mongodbatlas_service_account_access_list_entry` | IP access list entry |
---
### Migration Steps
For complete working examples, see the [organization-level migration example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.22.0/examples/migrate_pak_to_service_account/org_level).
### Step 1: Initial Configuration - PAK Resources Only
Original configuration with PAK resources:
```terraform
resource "mongodbatlas_api_key" "this" {
org_id = var.org_id
description = "Example API Key"
role_names = ["ORG_MEMBER"]
}
# Project assignment for the API Key
resource "mongodbatlas_api_key_project_assignment" "this" {
project_id = var.project_id
api_key_id = mongodbatlas_api_key.this.api_key_id
roles = ["GROUP_READ_ONLY", "GROUP_DATA_ACCESS_READ_ONLY"]
}
# IP Access List entry for the API Key
resource "mongodbatlas_access_list_api_key" "this" {
org_id = var.org_id
api_key_id = mongodbatlas_api_key.this.api_key_id
cidr_block = "192.168.1.100/32"
# Alternative: ip_address = "192.168.1.100"
}
```
### Step 2: Intermediate State - Add Service Account Resources Alongside Existing PAK Resources
Add the Service Account resources to your configuration while keeping the existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs. The `without_initial_secret` attribute requires provider v2.19.0 or later.
```terraform
resource "mongodbatlas_service_account" "this" {
org_id = var.org_id
name = "example-service-account"
description = "Example Service Account"
roles = ["ORG_MEMBER"]
without_initial_secret = true
}
# Create the secret explicitly so this configuration owns it and can rotate it later.
resource "mongodbatlas_service_account_secret" "this" {
org_id = var.org_id
client_id = mongodbatlas_service_account.this.client_id
secret_expires_after_hours = 2160 # 90 days
}
resource "mongodbatlas_service_account_project_assignment" "this" {
project_id = var.project_id
client_id = mongodbatlas_service_account.this.client_id
roles = ["GROUP_READ_ONLY", "GROUP_DATA_ACCESS_READ_ONLY"]
}
resource "mongodbatlas_service_account_access_list_entry" "this" {
org_id = var.org_id
client_id = mongodbatlas_service_account.this.client_id
cidr_block = "192.168.1.100/32"
# Alternative: ip_address = "192.168.1.100"
}
output "service_account_secret" {
description = "The secret value for the Service Account. Returned only when the secret is created."
value = mongodbatlas_service_account_secret.this.secret
sensitive = true
}
```
**Apply and test:**
1. Run `terraform plan` to review the changes.
2. Run `terraform apply` to create the Service Account resources.
3. Retrieve and securely store the `service_account_secret` value (**warning**: this prints the secret to your terminal):
```bash
terraform output -raw service_account_secret
```
4. Test your Service Account in your applications and verify that both PAK and SA authentication methods work correctly.
5. Re-run `terraform plan` to ensure you have no unexpected changes: `No changes. Your infrastructure matches the configuration.`
### Step 3: Final State - Remove PAK Resources, SA Resources Only
Once you have verified that the Service Account works correctly, remove the PAK resources from your configuration:
```terraform
resource "mongodbatlas_service_account" "this" {
org_id = var.org_id
name = "example-service-account"
description = "Example Service Account"
roles = ["ORG_MEMBER"]
without_initial_secret = true
}
# Create the secret explicitly so this configuration owns it and can rotate it later.
resource "mongodbatlas_service_account_secret" "this" {
org_id = var.org_id
client_id = mongodbatlas_service_account.this.client_id
secret_expires_after_hours = 2160 # 90 days
}
resource "mongodbatlas_service_account_project_assignment" "this" {
project_id = var.project_id
client_id = mongodbatlas_service_account.this.client_id
roles = ["GROUP_READ_ONLY", "GROUP_DATA_ACCESS_READ_ONLY"]
}
resource "mongodbatlas_service_account_access_list_entry" "this" {
org_id = var.org_id
client_id = mongodbatlas_service_account.this.client_id
cidr_block = "192.168.1.100/32"
}
```
1. Run `terraform plan` to verify:
- PAK resources are planned for destruction
- Only the Service Account resources remain
- No unexpected changes
2. Run `terraform apply` to finalize the migration. This will delete the PAK resources from Atlas.
3. Verify that your applications and infrastructure continue to work with Service Accounts.
4. Re-run `terraform plan` to ensure you have no planned changes: `No changes. Your infrastructure matches the configuration.`
---
Project-Level Migration
## Project-Level API Keys to Service Accounts
**Objective**: Migrate from project-level PAK resources (`mongodbatlas_project_api_key`, `mongodbatlas_access_list_api_key`) to project-level Service Account resources (`mongodbatlas_project_service_account`, `mongodbatlas_project_service_account_access_list_entry`).
**Important:** Organization-level resources (`mongodbatlas_service_account`) are the recommended approach. Project-level resources (`mongodbatlas_project_service_account`) should only be used if you do not have organization-level permissions to manage Service Accounts. Otherwise, use the [Organization-Level Migration](#organization-level-api-keys-to-service-accounts) approach.
### Resource Mapping
The following table shows the mapping between project-level PAK resources and their Service Account equivalents:
| PAK Resource | Service Account Resource | Notes |
|--------------|-------------------------|-------|
| `mongodbatlas_project_api_key` | `mongodbatlas_project_service_account` | Project-level API key / Service Account (use only if you don't have org-level permissions) |
| `mongodbatlas_access_list_api_key` | `mongodbatlas_project_service_account_access_list_entry` | IP access list entry for project-level Service Account |
**Important:** Organization-level resources (`mongodbatlas_service_account`) are the recommended approach. Project-level resources (`mongodbatlas_project_service_account`) should only be used if you do not have organization-level permissions to manage Service Accounts.
---
### Migration Steps
For complete working examples, see the [project-level migration example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.22.0/examples/migrate_pak_to_service_account/project_level).
### Step 1: Initial Configuration - PAK Resources Only
Original configuration with PAK resources:
```terraform
resource "mongodbatlas_project_api_key" "this" {
description = "Example Project API Key"
project_assignment {
project_id = var.project_id
role_names = ["GROUP_READ_ONLY", "GROUP_DATA_ACCESS_READ_ONLY"]
}
}
# IP Access List entry for the API Key
resource "mongodbatlas_access_list_api_key" "this" {
org_id = var.org_id
api_key_id = mongodbatlas_project_api_key.this.api_key_id
cidr_block = "192.168.1.100/32"
# Alternative: ip_address = "192.168.1.100"
}
```
### Step 2: Intermediate State - Add Service Account Resources Alongside Existing PAK Resources
Add the Service Account resources to your configuration while keeping the existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs. The `without_initial_secret` attribute requires provider v2.19.0 or later.
```terraform
resource "mongodbatlas_project_service_account" "this" {
project_id = var.project_id
name = "example-project-service-account"
description = "Example Project Service Account"
roles = ["GROUP_READ_ONLY", "GROUP_DATA_ACCESS_READ_ONLY"]
without_initial_secret = true
}
# Create the secret explicitly so this configuration owns it and can rotate it later.
resource "mongodbatlas_project_service_account_secret" "this" {
project_id = var.project_id
client_id = mongodbatlas_project_service_account.this.client_id
secret_expires_after_hours = 2160 # 90 days
}
resource "mongodbatlas_project_service_account_access_list_entry" "this" {
project_id = var.project_id
client_id = mongodbatlas_project_service_account.this.client_id
cidr_block = "192.168.1.100/32"
# Alternative: ip_address = "192.168.1.100"
}
output "project_service_account_secret" {
description = "The secret value for the Project Service Account. Returned only when the secret is created."
value = mongodbatlas_project_service_account_secret.this.secret
sensitive = true
}
```
**Apply and test:**
1. Run `terraform plan` to review the changes.
2. Run `terraform apply` to create the Service Account resource.
3. Retrieve and securely store the `project_service_account_secret` value (**warning**: this prints the secret to your terminal):
```bash
terraform output -raw project_service_account_secret
```
4. Test your Service Account in your applications and verify that both PAK and SA authentication methods work correctly.
5. Re-run `terraform plan` to ensure you have no unexpected changes: `No changes. Your infrastructure matches the configuration.`
### Step 3: Final State - Remove PAK Resources, SA Resources Only
Once you have verified that the Service Account works correctly, remove the PAK resources from your configuration:
```terraform
resource "mongodbatlas_project_service_account" "this" {
project_id = var.project_id
name = "example-project-service-account"
description = "Example Project Service Account"
roles = ["GROUP_READ_ONLY", "GROUP_DATA_ACCESS_READ_ONLY"]
without_initial_secret = true
}
# Create the secret explicitly so this configuration owns it and can rotate it later.
resource "mongodbatlas_project_service_account_secret" "this" {
project_id = var.project_id
client_id = mongodbatlas_project_service_account.this.client_id
secret_expires_after_hours = 2160 # 90 days
}
resource "mongodbatlas_project_service_account_access_list_entry" "this" {
project_id = var.project_id
client_id = mongodbatlas_project_service_account.this.client_id
cidr_block = "192.168.1.100/32"
}
```
1. Run `terraform plan` to verify:
- PAK resources are planned for destruction
- Only the Service Account resources remain
- No unexpected changes
2. Run `terraform apply` to finalize the migration. This will delete the PAK resource from Atlas.
3. Verify that your applications and infrastructure continue to work with Service Accounts.
4. Re-run `terraform plan` to ensure you have no planned changes: `No changes. Your infrastructure matches the configuration.`
---
## Switching the Provider Authentication Method
After migrating your Terraform-managed resources from PAK to SA, you may also want to switch the Terraform provider authentication method.
For detailed instructions on configuring Service Account authentication for the provider, see the [Provider Configuration guide](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/provider-configuration).
**Note:** The Service Account used for provider authentication should be created in a separate Terraform configuration or managed outside of Terraform. It is recommended to manage provider authentication credentials separately from the resources they manage to avoid potential lockout scenarios.