Get Started with the Atlas Administration API

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.

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

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

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:

Grant Programmatic Access to an Organization

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

atlas organizations apiKeys create [options]

atlas organizations apiKeys accessLists create [options]

Grant Programmatic Access to a Project

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

atlas projects apiKeys assign <ID> [options]

atlas projects apiKeys create [options]

Make an API Request

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>

Example API Request

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

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:

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:

• Manage Programmatic Access to an Organization.

• Manage Programmatic Access to Multiple Organizations.

• Manage Programmatic Access to a Project.