Navigation
  • API >
  • Configure Atlas API Access

Configure Atlas API Access

On this page

To access the Atlas API, generate an API key for your organization.

Personal API Key Deprecation

Atlas has deprecated Personal API Keys. You cannot create new Personal API Keys, but existing Personal API Keys continue to function.

Programmatic API Keys can’t use the Cloud Manager Console

Organization API keys aren’t associated with user credentials and can’t log in to the Atlas user interface.

Prerequisite

Enable API Whitelisting for Your Organization

For Atlas users with a non-empty API whitelist, all API access must originate from a whitelisted IPv4 address. Ensure your configured whitelist entries provide appropriate coverage for all clients which require API access. An empty API whitelist grants access to all API endpoints except those that explicitly require whitelisting.

You can configure Atlas to require API whitelisting at the organization level. When this setting is enabled, all API calls within that organization must originate from an entry on each respective Atlas user’s API whitelist. For organizations that require API whitelisting, Atlas users cannot access any API operations until they define at least one API whitelist entry.

To require an API whitelist for an Organization:

1

Log in to Atlas.

2

Navigate to the Settings page for your organization.

  1. If it is not already displayed, select your desired organization from the office icon Organizations menu in the navigation bar.
  2. Click the Organization Settings icon next to the Organizations menu.
3

Toggle the Require IP Whitelist for Public API setting to On.

For a description of the Atlas API’s principles and conventions, see the API.

Programmatic API Keys

To grant programmatic access to an organization or project using only the API, you can create an API key. API keys:

  • Have two parts: a Public Key and a Private Key.
  • Cannot be used to log into Atlas through the user interface.
  • Must be granted roles as you would Users to make sure the API Keys can call API endpoints without errors.
  • Can belong to one organization, but may be granted access to any number of projects in that organization.

Manage Programmatic Access to an Organization

Required Permissions

To perform any of the following actions, you must have the Organization Owner role.

Create an API Key in an Organization

1

Navigate to the Access Manager page for your organization.

  1. If it is not already displayed, select your desired organization from the office icon Organizations menu in the navigation bar.
  2. Click Access Manager in the sidebar, or click Access Manager in the navigation bar, then click your organization.
2

Click the API Keys tab

3

Create an API Key.

  1. Click Manage.
  2. Select Create API Key.
4

On the Add API Key page, 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.
5

Copy and save the Public Key.

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

6

Click Next.

7

Copy and save the Private Key.

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

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.

8

Add an API Whitelist.

  1. Click Add Whitelist Entry.

  2. Enter an IPv4 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 also will make API requests using this API Key.

  3. Click Save.

9

Click Done.

View the Details of an API Key in an Organization

1

Navigate to the Access Manager page for your organization.

  1. If it is not already displayed, select your desired organization from the office icon Organizations menu in the navigation bar.
  2. Click Access Manager in the sidebar, or click Access Manager in the navigation bar, then click your organization.
2

Click the API Keys tab

3

From the ellipsis menu to the right of the API Key, click View Details.

The <Public Key> API Key Details modal displays:

  • The obfuscated Private Key
  • The date the Key was last used
  • The date the Key was created
  • The IPv4 addresses on which the Key is whitelisted
  • The projects to which the Key has been granted access

Change an API Key in an Organization

You can change the roles, description, or whitelist of an API Key in an Organization.

1

Navigate to the Access Manager page for your organization.

  1. If it is not already displayed, select your desired organization from the office icon Organizations menu in the navigation bar.
  2. Click Access Manager in the sidebar, or click Access Manager in the navigation bar, then click your organization.
2

Click the API Keys tab

3

From the ellipsis menu to the right of the API Key you want to change, click Edit.

4

On the Add API Key page, edit the API Key Information.

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

Click Next.

6

Edit the API Whitelist.

  1. To add an IP address from which you want Atlas to accept API requests for this API Key, click Add Whitelist Entry and type an IPv4 address.

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

  2. To remove a whitelisted IP address, click trash icon to the right of the whitelisted IP address.

  3. Click Save.

7

Click Done.

Delete an API Key from an Organization

1

Navigate to the Access Manager page for your organization.

  1. If it is not already displayed, select your desired organization from the office icon Organizations menu in the navigation bar.
  2. Click Access Manager in the sidebar, or click Access Manager in the navigation bar, then click your organization.
2

Click the API Keys tab

3

Click trash icon to the right of the API Key that you want to delete.

4

Click Delete to confirm that you want to delete this API Key or Cancel to leave the key in the Organization.

Removing an API Key from an Organization also removes that key from any projects to which the key was granted access.

Manage Programmatic Access to a Project

Required Permissions

To perform any of the following actions, you must have the Project Owner role.

Create an API Key for a Project

1

Navigate to the Access Manager page for your project.

  1. If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
  2. If it is not already displayed, select your desired project from the Project menu in the navigation bar.
  3. Click Access Manager in the navigation bar, then click your project.
2

Click the API Keys tab

3

Create an API Key.

  1. Click Manage.
  2. Select Create API Key.
4

On the Add API Key page, enter the API Key Information.

  1. Enter a Description.
  2. In the Project Permissions menu, select the new role or roles for the API key.
5

Copy and save the Public Key.

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

6

Click Next.

7

Copy and save the Private Key.

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

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.

8

Add an API Whitelist.

  1. Click Add Whitelist Entry.

  2. Enter an IPv4 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 also will make API requests using this API Key.

  3. Click Save.

9

Click Done.

View the Details of an API Key in a Project

1

Navigate to the Access Manager page for your project.

  1. If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
  2. If it is not already displayed, select your desired project from the Project menu in the navigation bar.
  3. Click Access Manager in the navigation bar, then click your project.
2

Click the API Keys tab

3

From the ellipsis menu to the right of the API Key, click View Details.

The <Public Key> API Key Details modal displays the obfuscated Private Key, the date the key was last used, the date it was created, and the IPv4 addresses on which the key is whitelisted.

Change an API Key’s Roles in a Project

1

Navigate to the Access Manager page for your project.

  1. If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
  2. If it is not already displayed, select your desired project from the Project menu in the navigation bar.
  3. Click Access Manager in the navigation bar, then click your project.
2

Click the API Keys tab

3

From the ellipsis menu to the right of the API Key, click Edit Permissions.

4

Select the new role or roles for the API Key from the Project Permissions menu.

5

Click the check icon to save.

Edit an API Key’s Whitelist

Required Permissions

To edit a project API key’s whitelist, you must have the Organization Owner role.

1

Navigate to the Access Manager page for your project.

  1. If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
  2. If it is not already displayed, select your desired project from the Project menu in the navigation bar.
  3. Click Access Manager in the navigation bar, then click your project.
2

Click the API Keys tab

3

From the ellipsis menu to the right of the API Key, click Edit Whitelist.

Note

Selecting Edit Whitelist takes you to the organization level of the Atlas UI.

4

Edit the API Whitelist.

Note

You cannot edit an individual whitelist entry. If you need to modify a whitelist entry, delete and re-create it.

  1. To add an IP address from which you want Atlas to accept API requests for this API Key, click Add Whitelist Entry and type an IPv4 address.

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

  2. To remove a whitelisted IP address, click trash icon to the right of the whitelisted IP address.

  3. Click Save.

5

Click Done.

Delete an API Key from a Project

1

Navigate to the Access Manager page for your project.

  1. If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
  2. If it is not already displayed, select your desired project from the Project menu in the navigation bar.
  3. Click Access Manager in the navigation bar, then click your project.
2

Click the API Keys tab

3

Click trash icon to the right of the API Key that you want to delete.

4

Click Delete to confirm that you want to delete this API Key or Cancel to leave the key in the project.

Personal API Keys (Deprecated)

Important

Personal API keys are deprecated, use Programmatic API Keys instead.

You can no longer create Personal API Keys. You can manage any Personal API Keys that you have currently.

To manage any existing personal API keys:

1

Navigate to the Personalization page.

  1. In the upper right corner of the Atlas UI, click your username to access the Account menu.
  2. Under Atlas, click User Preferences.
2

In the sidebar, click Public API Access.

When accessing Atlas through the API, you have the same level of access as you do through the Atlas interface. Your Atlas roles apply to both the interface and the API.

Limit API Operations to Whitelisted IPv4 Addresses

To access whitelisted API operations, you must configure your API whitelist with the IPv4 addresses from which you will issue the whitelisted commands. You also must have the Organization Owner role to issue whitelisted commands.

Address-based whitelists protect API operations. Only client requests that originate from a whitelisted IPv4 address are permitted to perform the operations.

Users have their own whitelists and own API keys. When you issue an API call, you must use an API key from your user account and must issue the command from an address on your user account’s whitelist. You cannot use your key to issue a whitelisted API request from an address on another user’s whitelist, unless, of course, you’ve added that address to your own whitelist.

On the resources pages in this guide, whitelisted operations are marked as such.

Add an IPv4 Address to the API Whitelist

1

Navigate to the Personalization page.

  1. In the upper right corner of the Atlas UI, click your username to access the Account menu.
  2. Under Atlas, click User Preferences.
2

In the sidebar, click Public API Access.

3

Add entries to the API whitelist.

  1. In the Personal API Key Whitelist section, click Add.

  2. Enter an IPv4 address or CIDR range. To add multiple entries to your whitelist, repeat this step. If you leave your whitelist empty, you have no access to whitelisted operations.

    You can enter any of the following:

    Entry Grants
    An IPv4 address Access to whitelisted operations from that address.
    A CIDR-notated range of IPv4 addresses Access to whitelisted operations from those addresses.

Delete an IPv4 Address from the API Whitelist

1

Navigate to the Personalization page.

  1. In the upper right corner of the Atlas UI, click your username to access the Account menu.
  2. Under Atlas, click User Preferences.
2

In the sidebar, click Public API Access.

3

Delete an entry from the API whitelist.

  1. In the Personal API Key Whitelist section, click the ellipsis menu to the right of the whitelist entry you want to delete.
  2. Click Delete.”
  3. Click Confirm to confirm that you want to delete this whitelist entry or Cancel to leave the entry in the whitelist.
←   API API Resources  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.