Docs Menu
Docs Home
/
MongoDB Atlas
/ /

Get Started with the Atlas Administration API

On this page

  • Grant Programmatic Access to Atlas
  • Optional: Require an IP Access List for the Atlas Administration API
  • Grant Programmatic Access to an Organization
  • Grant Programmatic Access to a Project
  • Make an API Request
  • Example API Request
  • Next Steps

Important

Each Atlas Administration API has its own resources and requires initial setup. The Atlas Administration API and the App Services Admin API also use different access keys from the Data API.

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.

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.

  • 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.

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

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. For usage details, see Make an API Request.

Atlas allows your Atlas Administration API keys to make requests from any address on the internet unless you require an IP access list for the Atlas Administration API. If you require an IP access list, your API keys can make API requests only from the location-based IP or CIDR addresses that you specify in the IP access list.

Each API key has its own IP access list. If you require an IP access list for all Atlas Administration API requests, you must define at least one IP access list entry for an API key before you can use the API key.

When you create a new organization using the Atlas UI, Atlas enables the API access list requirement by default. To disable the IP access list requirement when you create an organization, toggle Require IP Access List for the Atlas Administration API to OFF.

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

1
  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.

2

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.

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

1
  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.

2

Use the following procedures to grant programmatic access to an organization. To learn more, see Manage Programmatic Access to an Organization.

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

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

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
  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
3
  1. Enter a Description.

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

4
5

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

6

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
  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

Use the following procedures to grant programmatic access to a project. To learn more, see Manage Programmatic Access to a Project.

To perform any of the following actions, you must have Project Owner access to the 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 invite an organization API key to a project using the Atlas UI:

1
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

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

  3. Next to the Projects menu, expand the Options menu, then click Project Settings.

2

Click Access Manager in the sidebar.

3
4
  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.

5

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
  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

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

1
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

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

  3. Next to the Projects menu, expand the Options menu, then click Project Settings.

2

Click Access Manager in the sidebar.

3
4

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.

5
6

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

7

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.

8
  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.

9

The Atlas Administration API uses HTTP Digest Authentication to authenticate requests. When constructing a HTTP request, you must provide your programmatic API public key and corresponding private key as the username and password. To learn how to configure API access for an Atlas project, see Grant Programmatic Access to Atlas.

All Atlas Administration API endpoints have the following base URL:

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

Your request should resemble the following examples, where {PUBLIC-KEY} is your API public key and {PRIVATE-KEY} is the corresponding private key.

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.2023-02-01+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.2023-02-01+json" \
--include \
--request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \
--data '
{
"name": "MyProject",
"orgId": "5a0a1e7e0f2912c554080adc"
}'

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
2

The Import window displays.

3
4
5

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