Docs Menu
Docs Home
/
MongoDB Atlas
/
Programmatic Access
/
Atlas Administration API

Get Started with the Atlas Administration API

On this page

Important

Each Atlas Administration API has its own resources and requires initial setup.

You can access the Atlas Administration API servers through the public internet only. The Atlas Administration API is not available over connections that use network peering or private endpoints.

To learn more, see Atlas Programmatic Access.

The Atlas Administration API follows the principles of the REST architectural style to expose a number of internal resources which enable programmatic access to Atlas's features. To learn more, see Atlas Administration API Reference.

Grant Programmatic Access to Atlas

You can grant programmatic access to an organization or project using one of the two following authentication methods:

Service Account
API Keys

New method of authenticating to Atlas using the industry standard OAuth 2.0 protocol with the Client Credentials flow.

Legacy method of authenticating to Atlas that uses HTTP Digest Authentication.

A service account lets you manage permissions and create access tokens. A service account has a client ID and a secret that function as a username and a password for creating access tokens. An access token lets you make API requests to Atlas.

API keys have two parts: a Public Key and a Private Key. These two parts serve the same function as a username and a password when you make API requests to Atlas.

After you create a service account, you'll use its client ID and secret to generate an access token, which authenticates your API requests. Access tokens are only valid for 1 hour (3600 seconds) per the OAuth 2.0 specification. Expiration of access tokens prevents replay attacks, where a leaked access token could be used without a time restriction.

Atlas hashes the Public Key and Private Key using a unique value called a nonce. The nonce is only valid for a short amount of time as per the HTTP Digest Authentication specification. This is to prevent replay attacks, so you can't cache a nonce and use it forever.

Atlas roles limit which operations a service account can perform with its access token. You must grant roles to service accounts as you would for users to ensure the access token can call API endpoints without errors.

Atlas roles limit which operations API keys can perform. You must grant roles to API keys as you would for users to ensure the API keys can call API endpoints without errors.

Atlas binds many resources to a project. Many API resource URLs follow the format of /api/atlas/<version>/groups/<GROUP-ID>/, where <GROUP-ID> is your project ID. For these resources, the service account must be a member of the organization that hosts the project. Otherwise, Atlas responds with a 401 error. To give the organization-level service account access to a project, see Assign Existing Organization Access to a Project.

Atlas binds many resources to a project. Many API resource URLs follow the format of /api/atlas/<version>/groups/<GROUP-ID>/, where <GROUP-ID> is your project ID. For these resources, the API keys must be a member of the organization that hosts the project. Otherwise, Atlas responds with a 401 error. To give the organization-level API keys access to a project, see Assign Existing Organization Access to a Project.

Each service account belongs to only one organization, but you can grant a service account access to any number of projects in that organization.

Each API key belongs to only one organization, but you can grant API keys access to any number of projects in that organization.

You can't use a service account or its access token to log into Atlas through the Atlas UI.

You can't use API keys to log into Atlas through the Atlas UI.

Optional: Require an IP Access List for the Atlas Administration API

When you create an organization using the Atlas UI, Atlas enables the API IP access list feature by default. This limits API requests to only those from the location-based IP or CIDR addresses that you specify in the IP access list. If you make a request to the Atlas Administration API without an IP access list entry, the server responds with a 403 status code.

If you disable the feature, you can make API requests from any address on the internet as long as the IP access list is empty. Once you add an IP access list entry, only requests originating from that IP address can make requests.

To set your organization to require IP access lists for every Atlas Administration API request after organization creation, follow these steps:

1

In Atlas, go to the Organization Settings page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Click the Organization Settings icon next to the Organizations menu.

    The Organization Settings page displays.

2

Toggle the Require IP Access List for the Atlas Administration API setting to On.

Grant Programmatic Access to an Organization

Use the following procedures to grant programmatic access to an organization either through a service account or API keys. To learn more about these two authentication methods, see Atlas Administration API Authentication.

Required Access

To perform the following actions, you must have Organization Owner access to Atlas.

1

In Atlas, go to the Organization Access Manager page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Do one of the following steps:

    • Select Organization Access from the Access Manager menu in the navigation bar.

    • Click Access Manager in the sidebar.

    The Organization Access Manager page displays.

2

Click Add new Service Account.

3

Enter the service account information.

  1. Enter a Name.

  2. Enter a Description.

  3. Select a duration from the Client Secret Expiration menu.

  4. From the Organization Permissions menu, select the new role or roles for the service account.

4

Click Create.

5

Copy and save the Client Secret.

The client secret acts as the password when creating access tokens.

Warning

This is the only time you can view the full client secret. Click Copy and save it to a secure location. Otherwise, you'll need to generate a new client secret.

6

Add an API Access List Entry.

  1. Click Add Access List Entry.

  2. Enter an IP address or CIDR block from which you want Atlas to accept API requests for this service account.

    You can also click Use Current IP Address if the host you are using to access Atlas will also make API requests using this service account.

  3. Click Save.

You can use the Atlas Administration API to create a service account for your organization.

After you've created the service account, copy and save the {CLIENT-ID} and {CLIENT-SECRET} from the output, which should look similar to the following example. This is the only time you can view the full client secret. You'll need this information when you make an API request.

{
  "createdAt" : "2024-04-23T17:47:17Z",
  "description" : "Service account for my organization.",
  "clientId" : "{CLIENT-ID}",
  "name" : "My Service Account",
  "roles" : [ "ORG_MEMBER" ],
  "secrets" : [ {
    "createdAt" : "2024-04-23T17:47:17Z",
    "expiresAt" : "2024-12-01T00:00:00Z",
    "id" : "6627f7259d39d858378c9e30",
    "lastUsedAt" : null,
    "secret" : "{CLIENT-SECRET}"
   } ]
}%

Create an API Key

To create an API key in an organization using the Atlas CLI, run the following command:

atlas organizations apiKeys create [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas organizations apiKeys create.

Tip

See: Related Links

Add an API Access List Entry for the API Key

To create an IP access list entry for your API key using the Atlas CLI, run the following command:

atlas organizations apiKeys accessLists create [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas organizations apiKeys accessLists create.

1

In Atlas, go to the Organization Access Manager page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Do one of the following steps:

    • Select Organization Access from the Access Manager menu in the navigation bar.

    • Click Access Manager in the sidebar.

    The Organization Access Manager page displays.

2

Click Add new API Key.

3

Enter the API Key Information.

  1. Enter a Description.

  2. In the Organization Permissions menu, select the new role or roles for the API key.

4

Click Next.

5

Copy and save the Public Key.

The public key acts as the username when making API requests.

6

Copy and save the Private Key.

The private key acts as the password when making API requests.

Warning

Copy and save Public and Private Keys

The Private Key is only shown once: on this page. Click the Copy button to add the Private Key to the clipboard. Save and secure both the Public and Private Keys.

7

Add an API Access List Entry.

  1. Click Add Access list Entry.

  2. Enter an IP address or CIDR block from which you want Atlas to accept API requests for this API Key.

    You can also click Use Current IP Address if the host you are using to access Atlas will also make API requests using this API Key.

  3. Click Save.

8

Click Done.

Grant Programmatic Access to a Project

Use the following procedures to grant programmatic access to a project either through a service account or API keys. To learn more about these two authentication methods, see Atlas Administration API Authentication.

Required Access

To give a service account access to a project, you must have Organization Owner access to the organization that owns the project.

To give API keys access to a project, you must have Project Owner access for that project.

Assign Existing Organization Access to a Project

If you've already created service accounts or API keys for an organization, you can assign them to a project to grant that project access to the Atlas Administration API.

Warning

If you assign an organization service account to a project, the Project Owner can manage the service account, including rotating secrets and updating the IP access list.

1

In Atlas, go to the Project Access Manager page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. Do one of the following steps:

    • Select Project Access from the Access Manager menu in the navigation bar.

    • Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.

    The Project Access Manager page displays.

2

Click Invite to Project.

3

Locate your organization service account.

Start typing the client ID of your service account in the field, then select your service account from the menu.

4

Assign project roles to your service account.

In the menu that appears, select the new role or roles for the service account.

5

Click Invite to Project.

You can use the Atlas Administration API to grant an existing service account access to a project.

To assign an API key to a project using the Atlas CLI, run the following command:

atlas projects apiKeys assign <ID> [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas projects apiKeys assign.

To assign organization API keys to a project using the Atlas UI:

1

In Atlas, go to the Project Access Manager page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. Do one of the following steps:

    • Select Project Access from the Access Manager menu in the navigation bar.

    • Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.

    The Project Access Manager page displays.

2

Click Invite to Project.

3

Add the API Key to the project.

  1. Type the public key into the field.

  2. In the Project Permissions menu, select the new role or roles for the API key.

4

Click Invite to Project.

Add Project Access from a Project

If you haven't already created a service account or API keys for an organization, you can create them for a project to grant that project access to the Atlas Administration API. The service account or API keys that you create for a project are automatically added to the parent organization with the permission Organization Member.

To create a service account for a project using the Atlas UI:

1

In Atlas, go to the Project Access Manager page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. Do one of the following steps:

    • Select Project Access from the Access Manager menu in the navigation bar.

    • Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.

    The Project Access Manager page displays.

2

Click Create Application Service Account.

3

Enter the service account information.

  1. Enter a Name.

  2. Enter a Description.

  3. Select a duration from the Client Secret Expiration menu.

  4. From the Project Permissions menu, select the new role or roles for the service account.

4

Click Create.

5

Copy and save the Client Secret.

The client secret acts as the password when creating access tokens.

Warning

This is the only time you can view the full client secret. Click Copy and save it to a secure location. Otherwise, you'll need to generate a new client secret.

6

Add an API Access List Entry.

  1. Click Add Access List Entry.

  2. Enter an IP address or CIDR block from which you want Atlas to accept API requests for this service account.

    You can also click Use Current IP Address if the host you are using to access Atlas will also make API requests using this service account.

  3. Click Save.

You can use the Atlas Administration API to create a service account for your project.

After you've created the service account, copy and save the {CLIENT-ID} and {CLIENT-SECRET} from the output, which should look similar to the following example. This is the only time you can view the full client secret. You'll need this information when you make an API request.

{
  "createdAt" : "2024-04-23T17:47:17Z",
  "description" : "Service account for my organization.",
  "clientId" : "{CLIENT-ID}",
  "name" : "My Service Account",
  "roles" : [ "ORG_MEMBER" ],
  "secrets" : [ {
    "createdAt" : "2024-04-23T17:47:17Z",
    "expiresAt" : "2024-12-01T00:00:00Z",
    "id" : "6627f7259d39d858378c9e30",
    "lastUsedAt" : null,
    "secret" : "{CLIENT-SECRET}"
   } ]
}%

To create an API key for your project using the Atlas CLI, run the following command:

atlas projects apiKeys create [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas projects apiKeys create.

After you create the API key for your project, use the Atlas UI to add an API access list entry. You can't use the API key for the project until you set up the API access list.

Note

Atlas CLI Limitation

You can't edit the API access list for a project API key using the Atlas CLI.

To add an API access list entry using the Atlas UI:

1

Add an API Access List Entry.

  1. Click Add Access List Entry.

  2. Enter an IP address from which you want Atlas to accept API requests for this API Key. You can also click Use Current IP Address if the host you are using to access Atlas will also make API requests using this API Key.

  3. Click Save.

2

Click Done.

To create an API key for a project using the Atlas UI:

1

In Atlas, go to the Project Access Manager page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. Do one of the following steps:

    • Select Project Access from the Access Manager menu in the navigation bar.

    • Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.

    The Project Access Manager page displays.

2

Click Create Application API Key.

3

Enter the API Key Information.

On the Create API Key page:

  1. Enter a Description.

  2. In the Project Permissions menu, select the new role or roles for the API key.

4

Click Next.

5

Copy and save the Public Key.

The public key acts as the username when making API requests.

6

Copy and save the Private Key.

The private key acts as the password when making API requests.

Warning

Save Private Key

The Private Key is only shown once: on this page. Click the Copy button to add the Private Key to the clipboard. Save and secure both the Public and Private Keys.

7

Add an API Access List Entry.

  1. Click Add Access List Entry.

  2. Enter an IP address from which you want Atlas to accept API requests for this API Key.

    You can also click Use Current IP Address if the host you are using to access Atlas will also make API requests using this API Key.

  3. Click Save.

8

Click Done.

Make an API Request

The Atlas Administration API uses one of two authentication methods to authenticate requests: service account or API keys. You'll need the keys or secret that you saved when configuring your preferred authentication method to complete the following procedures.

All Atlas Administration API endpoints have the following base URL:

https://cloud.mongodb.com/api/atlas/<version>

To make an API request using a service account, use the service account to generate an access token, then use the access token in your request:

1

Retrieve the client secret for your service account.

Locate the client secret beginning with mdb_sa_sk_ that you saved immediately after creating the service account, which was the only time you could view the client secret. If you did not save the client secret, you must generate a new client secret.

2

Base64-encode the client ID and secret.

For example, run:

echo -n {CLIENT-ID}:{CLIENT-SECRET} | base64
3

Request an access token.

Replace {BASE64-AUTH} in the following example with the output from the preceding step, then run:

1curl --request POST \
2   --url https://cloud.mongodb.com/api/oauth/token \
3   --header 'accept: application/json' \
4   --header 'cache-control: no-cache' \
5   --header 'authorization: Basic {BASE64-AUTH}' \
6   --header 'content-type: application/x-www-form-urlencoded' \
7   --data 'grant_type=client_credentials'
{"access_token":"eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6ImYyZjE2YmE4LTkwYjUtNDRlZS1iMWYwLTRkNWE2OTllYzVhNyJ9.eyJpc3MiOiJodHRwczovL2Nsb3VkLWRldi5tb25nb2RiLmNvbSIsImF1ZCI6ImFwaTovL2FkbWluIiwic3ViIjoibWRiX3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImNpZCI6Im1kYl9zYV9pZF82NjI4MWJjNjAzYTcxYTQzMGI5MDZlZjciLCJhY3RvcklkIjoibWRiX3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImlhdCI6MTcxMzkwNTM1OSwiZXhwIjoxNzEzOTA4OTU5LCJqdGkiOiI4ZTg1MTM3YS0wZGU1LTQ0N2YtYTA0OS1hMmVmNTIwZGJhNTIifQ.AZSFvhcjwVcJYmvW6E_K5UnDmeiX2sJgL27vo5ElzeBuPawRciKkn6ervZ6IpUTx2HHllGgAAMmhaP9B66NywhfjAXC697X9KcOzm81DTtvDjLrFeRSc_3vFmeGvfUKKXljEdWBnbmwCwtBlO5SJuBxb1V5swAl-Sbq9Ymo4NbyepSnF","expires_in":3600,"token_type":"Bearer"}%

Important

The access token is valid for 1 hour (3600 seconds). You can't refresh an access token. When this access token expires, repeat this step to generate a new one.

4

Make an API call.

Replace {ACCESS-TOKEN} in the following example with the output from the preceding step.

The following sample GET request returns all projects in your organization:

curl --request GET \
     --url https://cloud.mongodb.com/api/atlas/v2/groups \
     --header 'Authorization: Bearer {ACCESS-TOKEN}' \
     --header 'Accept: application/vnd.atlas.2023-02-01+json' \
     --header 'Content-Type: application/json'

The following sample POST request takes a request body and creates a project named MyProject in your organization:

curl --header 'Authorization: Bearer {ACCESS-TOKEN}' \
      --header "Content-Type: application/json" \
      --header "Accept: application/vnd.atlas.2023-02-01+json" \
      --include \
      --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \
      --data '
         {
            "name": "MyProject",
            "orgId": "5a0a1e7e0f2912c554080adc"
         }'

Your request should resemble the following examples, where {PUBLIC-KEY} is your API public key and {PRIVATE-KEY} is the corresponding private key. To explore the available endpoints through the Atlas Administration API, you can use MongoDB's Postman workspace.

The following sample GET request returns all projects in your organization:

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
      --header "Content-Type: application/json" \
      --header "Accept: application/vnd.atlas.2024-08-05+json" \
      --include \
      --request GET "https://cloud.mongodb.com/api/atlas/v2/groups"

The following sample POST request takes a request body and creates a project named MyProject in your organization:

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
      --header "Content-Type: application/json" \
      --header "Accept: application/vnd.atlas.2024-08-05+json" \
      --include \
      --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \
      --data '
         {
            "name": "MyProject",
            "orgId": "5a0a1e7e0f2912c554080adc"
         }'

See also:

Alternatively, you can use any tool that supports OpenAPI v3 specification to generate code samples or mock servers. For example, you can import the Atlas Admin API Specification into Postman to generate curl commands. To use Postman to generate curl commands:

1

In the MongoDB Atlas Administration API documentation, right-click the Download button and copy the link.

2

Open Postman and click File, then Import.

The Import window displays.

3

In the Import window, click Link and paste the download link that you copied in step 1.

4

Click Continue, then Import.

5

For the request for which you want to generate a curl command, click </> on the right and select cURL from the Code snippet dropdown.

Rotate Service Account Secrets

Service account secrets expire after the duration specified when created, anywhere from 8 hours to 365 days. When it's time to rotate the secret, Atlas returns the alert Service Account Secrets are about to expire.

Note

To configure service account alerts, see Configure Alert Settings.

To rotate your service account secret, complete the following steps to generate a new client secret, update your application with the new client secret, and delete the old secret.

You can generate a new client secret and delete the old one using the Atlas UI.

1

In Atlas, go to the Organization Access Manager page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Do one of the following steps:

    • Select Organization Access from the Access Manager menu in the navigation bar.

    • Click Access Manager in the sidebar.

    The Organization Access Manager page displays.

2

Click the Applications tab.

3

Click Service Accounts.

4

Click the name of a service account.

5

Generate a new client secret.

  1. Click Generate New Client Secret

  2. Choose a duration for the client secret from the menu. The client secret expires after this duration.

  3. Click Generate New.

  4. Click Copy and save the client secret to a secure location. This is the only time you can view the full client secret.

  5. Click Close.

6

Update your application with the new client secret.

Important

Once you generate a new client secret, the old client secret expires within 7 days. This expiration period can be shorter depending on the old secret's original expiration date.

  • If the old secret is set to expire more than 7 days after the new one is created, its expiration is shortened to 7 days from the new secret's creation date.

  • If the old secret is set to expire in less than 7 days from the new one's creation date, the original expiration date is maintained.

To avoid losing access to the Atlas Administration API, update your application with the new client secret as soon as possible.

7

Delete the old client secret.

  1. In the Atlas UI for your service account, click Revoke.

  2. Confirm you want to delete the secret by typing the prompt in the field, then click Revoke Secret.

You can use the Atlas Administration API to:

Important

Once you generate a new client secret, the old client secret expires within 7 days. This expiration period can be shorter depending on the old secret's original expiration date.

  • If the old secret is set to expire more than 7 days after the new one is created, its expiration is shortened to 7 days from the new secret's creation date.

  • If the old secret is set to expire in less than 7 days from the new one's creation date, the original expiration date is maintained.

To avoid losing access to the Atlas Administration API, update your application with the new client secret as soon as possible.

Next Steps

To learn more about the Atlas Administration API, see Atlas Administration API Reference.

To manage programmatic access to the Atlas Administration API, see any of the following procedures:

Back

Atlas Administration API

Next

Organization Access