Docs Menu

Docs HomeLaunch & Manage MongoDBMongoDB Atlas

Get Started with the Atlas Administration API

On this page

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

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

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.

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.

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"
}'

Tip

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

←  Manage Deployments with the Atlas Administration APIManage Programmatic Access to an Organization →