Docs Menu

Get Started with the Atlas Administration API

On this page

Important

Each {atlas-admin-api+} has its own resources and requires initial setup. The Atlas Administration API and the Realm Admin API also use different access keys from the Data API.

To learn more, see APIs.

Required for All Resources: Generate an Organization API Key

To access the Atlas Administration API, Create an API Key in an Organization.

All API keys belong to the organization. You can give an API key access to a project. To add the new API key to a project, Invite an Organization API Key to a Project.

To learn more about managing API keys for your organization or project, see Grant Programmatic Access to Atlas.

Required for Select Resources: API Resource Request Access Lists

Atlas allows your API key to make requests from any address on the internet. Atlas has some exceptions to this rule. These exceptions limit which resources an API key can use without location-based limits defined in an API access list.

To add these location-based limits to your API key, create an API access list. This list limits the internet addresses from which a specific API key can make API requests.

Any API keys with an API access list require all API requests to come from an IP address on that list. Your API access list must include entries for all clients that use the API.

Use API Resources that Require an Access List

The following API resources require an API access list:

Organization API Access List Entries

Create or remove access list entries for an organization API key.

Cloud Backup Restores

Cloud Backup Snapshots

Take or remove one cloud backup snapshot.

Legacy Backups

Require an API Access List for All Requests

You can require all API requests from an API key to come from an entry on its API access list. If you require API access lists, API keys can't make any API requests until you define at least one API access list entry.

Procedure

To set your organization to require API access lists for every API key:

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 Organizations menu in the navigation bar.
  2. Click the Organization Settings icon next to the Organizations menu.
3
Toggle the Require IP Access List for the Atlas Administration API setting to On.

Grant Programmatic Access to Atlas

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

  • API keys have two parts: a Public Key and a Private Key. These two parts serve the same function as a username and a personal API key when you make API requests to Atlas.
  • You can't use an API key to log into Atlas through the user interface.
  • You must grant roles to API keys as you would for users to ensure the API keys can call API endpoints without errors.
  • Each API key belongs to only one organization, but you can grant an API key access to any number of projects in that organization.

Manage Programmatic Access to an Organization

Note
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 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 Create 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 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.
8
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 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
View the Access List.
  1. Click to the right of the API Key.
  2. 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 IP addresses from which the Key can access the API
  • The projects to which the Key has been granted access

Change an API Key in an Organization

You can change the roles, description, or access list 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 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
Edit the API Key Information.

On the Add API Key page:

  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 Access List.

  1. To add an IP address or CIDR block from which you want Atlas to accept API requests for this API Key, click Add Access list Entry and type an IP 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 an IP address from the access list, click to the right of the 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 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 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

Note
Required Permissions

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

Note
Requires Access List

To make this API request:

  1. Configure an IP access list.
  2. Add the IP addresses or CIDR blocks of your client applications to the access list using the console or API. If you host your application on AWS, you can use an AWS security group ID as well.

Changing an API key's access list might impact multiple organizations, projects, or both.

Invite an Organization API Key to 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 Organizations menu in the navigation bar.
  2. Select your desired project from the list of projects in the Projects page.
  3. Click the vertical ellipsis () next to your project name in the upper left corner and select Project Settings.
  4. Click Access Manager in the navigation bar, then click your project.
2
Click the API Keys tab.
3
Add the API Key to the project.
  1. Click Invite to Project.
  2. Type the public key into the field.
  3. In the Project Permissions menu, select the new role or roles for the API key.
4
Click Invite to Project.

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 Organizations menu in the navigation bar.
  2. Select your desired project from the list of projects in the Projects page.
  3. Click the vertical ellipsis () next to your project name in the upper left corner and select Project Settings.
  4. Click Access Manager in the navigation bar, then click your project.
2
Click Create 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.

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 Organizations menu in the navigation bar.
  2. Select your desired project from the list of projects in the Projects page.
  3. Click the vertical ellipsis () next to your project name in the upper left corner and select Project Settings.
  4. Click Access Manager in the navigation bar, then click your project.
2
Click the API Keys tab.
3
View the Access List.
  1. Click to the right of the API Key.
  2. Click View Details.

The <Public Key> API Key Details modal displays the following information:

  • The obfuscated Private Key
  • The date the key was last used
  • The date the key was created
  • The IP address or addresses from which the API key can access the API

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 Organizations menu in the navigation bar.
  2. Select your desired project from the list of projects in the Projects page.
  3. Click the vertical ellipsis () next to your project name in the upper left corner and select Project Settings.
  4. Click Access Manager in the navigation bar, then click your project.
2
Click the API Keys tab.
3
Edit the Access List.
  1. Click to the right of the API Key.
  2. Click Edit Permissions.
4
Select the new role or roles for the API Key from the Project Permissions menu.
5
Click the to save.

Edit an API Key's Access List

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 Organizations menu in the navigation bar.
  2. Select your desired project from the list of projects in the Projects page.
  3. Click the vertical ellipsis () next to your project name in the upper left corner and select Project Settings.
  4. Click Access Manager in the navigation bar, then click your project.
2
Click the API Keys tab.
3
Edit the Access List.
  1. Click to the right of the API Key.
  2. Click Edit Permissions.
Note

Selecting Edit Permissions takes you to the organization level of the Atlas console.

4
Edit the API Access List.

You cannot modify an existing API Key access list entry. You must delete and re-create it.

  1. Click to the right of the IP address to remove it.

  2. Add the new IP address from which you want Atlas to accept API requests for this API Key. Use one of the two options:

    • Click Add access list Entry and type an IP address, or
    • 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.
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 Organizations menu in the navigation bar.
  2. Select your desired project from the list of projects in the Projects page.
  3. Click the vertical ellipsis () next to your project name in the upper left corner and select Project Settings.
  4. Click Access Manager in the navigation bar, then click your project.
2
Click the API Keys tab.
3
Click 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.
←  Invitations to Organizations and ProjectsView Activity Feed →

On this page

Give Feedback
MongoDB logo
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center

Support

Social

© 2022 MongoDB, Inc.