Docs Menu
Docs Home
/
MongoDB Atlas
/
Programmatic Access
/
Atlas Administration API

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
  • Next Steps

Important

Each Atlas Administration API has its own resources and requires initial setup.

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.

Grant Programmatic Access to Atlas

You can grant programmatic access to an organization or project using one of the two following authentication methods:

API Keys
Service Account (Preview)

Legacy method of authenticating to Atlas that uses HTTP Digest Authentication.

New method of authenticating to Atlas using the industry standard OAuth 2.0 protocol with the Client Credentials flow. Currently in Preview.

API keys have two parts: a Public Key and a Private Key. These two parts serve the same function as a username and a password when you make API requests to Atlas.

A service account lets you manage permissions and create access tokens. A service account has a client ID and a secret that function as a username and a password for creating access tokens. An access token lets you make API requests to Atlas.

Atlas hashes the Public Key and Private Key using a unique value called a nonce. The nonce is only valid for a short amount of time as per the HTTP Digest Authentication specification. This is to prevent replay attacks, so you can't cache a nonce and use it forever.

After you create a service account, you'll use its client ID and secret to generate an access token, which authenticates your API requests. Access tokens are only valid for 1 hour (3600 seconds) per the OAuth 2.0 specification. Expiration of access tokens prevents replay attacks, where a leaked access token could be used without a time restriction.

Atlas roles limit which operations API keys can perform. You must grant roles to API keys as you would for users to ensure the API keys can call API endpoints without errors.

Atlas roles limit which operations a service account can perform with its access token. You must grant roles to service accounts as you would for users to ensure the access token can call API endpoints without errors.

Atlas binds many resources to a project. Many API resource URLs follow the format of /api/atlas/<version>/groups/<GROUP-ID>/, where <GROUP-ID> is your project ID. For these resources, the API keys must be a member of the organization that hosts the project. Otherwise, Atlas responds with a 401 error. To give the organization-level API keys access to a project, see Assign Existing Organization Access to a Project.

Atlas binds many resources to a project. Many API resource URLs follow the format of /api/atlas/<version>/groups/<GROUP-ID>/, where <GROUP-ID> is your project ID. For these resources, the service account must be a member of the organization that hosts the project. Otherwise, Atlas responds with a 401 error. To give the organization-level service account access to a project, see Assign Existing Organization Access to a Project.

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

Each service account belongs to only one organization, but you can grant a service account access to any number of projects in that organization.

You can't use API keys to log into Atlas through the Atlas UI.

You can't use a service account or its access token to log into Atlas through the Atlas UI.

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

Atlas lets you make Atlas Administration API requests from any address on the internet unless you require an IP access list, which limits API requests to only those from the location-based IP or CIDR addresses that you specify in the IP access list.

Each authentication method 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 your API keys or service accounts before you can use them to make API requests.

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

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

1

In Atlas, go to the Organization Settings page.

  1. If it's 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.

    The Organization Settings page displays.

2

Toggle the Require IP Access List for the Atlas Administration API setting to On.

Grant Programmatic Access to an Organization

Use the following procedures to grant programmatic access to an organization either through API keys or a service account. To learn more about these two authentication methods, see Atlas Administration API Authentication.

Important

Service accounts are currently in Preview. To learn more, see Service Accounts Overview.

Required Access

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

Create an API Key

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

Add an API Access List Entry for the API Key

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

In Atlas, go to the Organization Access Manager page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Do one of the following steps:

    • Select Organization Access from the Access Manager menu in the navigation bar.

    • Click Access Manager in the sidebar.

    The Organization Access Manager page displays.

2

Click Add new 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 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

Click Done.

1

In Atlas, go to the Organization Access Manager page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Do one of the following steps:

    • Select Organization Access from the Access Manager menu in the navigation bar.

    • Click Access Manager in the sidebar.

    The Organization Access Manager page displays.

2

Click Add new Service Account.

3

Enter the service account information.

  1. Enter a Name.

  2. Enter a Description.

  3. Select a duration from the Client Secret Expiration menu.

  4. From the Organization Permissions menu, select the new role or roles for the service account.

4

Click Create.

5

Copy and save the Client Secret.

The client secret acts as the password when creating access tokens.

Warning

This is the only time you can view the full client secret. Click Copy and save it to a secure location. Otherwise, you'll need to generate a new client secret.

6

Add an API Access List Entry.

  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 service account.

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

  3. Click Save.

You can use the Atlas Administration API to create a service account for your organization.

After you've created the service account, copy and save the {CLIENT-ID} and {CLIENT-SECRET} from the output, which should look similar to the following example. This is the only time you can view the full client secret. You'll need this information when you make an API request.

{
  "createdAt" : "2024-04-23T17:47:17Z",
  "description" : "Service account for my organization.",
  "clientId" : "{CLIENT-ID}",
  "name" : "My Service Account",
  "roles" : [ "ORG_MEMBER" ],
  "secrets" : [ {
    "createdAt" : "2024-04-23T17:47:17Z",
    "expiresAt" : "2024-12-01T00:00:00Z",
    "id" : "6627f7259d39d858378c9e30",
    "lastUsedAt" : null,
    "secret" : "{CLIENT-SECRET}"
   } ]
}%

Grant Programmatic Access to a Project

Use the following procedures to grant programmatic access to a project either through API keys or a service account. To learn more about these two authentication methods, see Atlas Administration API Authentication.

Important

Service accounts are currently in Preview. To learn more, see Service Accounts Overview.

Required Access

To give API keys access to a project, you must have Project Owner access for that project.

To give a service account access to a project, you must have Organization Owner access to the organization that owns the project.

Assign Existing Organization Access to a Project

If you've already created API keys or service accounts for an organization, you can assign them to a project to grant that project access to the Atlas Administration API.

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 assign organization API keys to a project using the Atlas UI:

1

In Atlas, go to the Project Access Manager page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

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

  3. Do one of the following steps:

    • Select Project Access from the Access Manager menu in the navigation bar.

    • Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.

    The Project Access Manager page displays.

2

Click Invite to Project.

3

Add the API Key to the project.

  1. Type the public key into the field.

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

4

Click Invite to Project.

Warning

If you assign an organization service account to a project, the Project Owner can manage the service account, including rotating secrets and updating the IP access list.

1

In Atlas, go to the Project Access Manager page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

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

  3. Do one of the following steps:

    • Select Project Access from the Access Manager menu in the navigation bar.

    • Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.

    The Project Access Manager page displays.

2

Click Invite to Project.

3

Locate your organization service account.

Start typing the client ID of your service account in the field, then select your service account from the menu.

4

Assign project roles to your service account.

In the menu that appears, select the new role or roles for the service account.

5

Click Invite to Project.

You can use the Atlas Administration API to grant an existing service account access to a project.

Add Project Access from a Project

If you haven't already created API keys or a service account for an organization, you can create them for a project to grant that project access to the Atlas Administration API. The API keys or service account that you create for a project are automatically added to the parent organization with the permission Organization Member.

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

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.

2

Click Done.

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

1

In Atlas, go to the Project Access Manager page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

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

  3. Do one of the following steps:

    • Select Project Access from the Access Manager menu in the navigation bar.

    • Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.

    The Project Access Manager page displays.

2

Click Create Application 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.

To create a service account for a project using the Atlas UI:

1

In Atlas, go to the Project Access Manager page.

  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

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

  3. Do one of the following steps:

    • Select Project Access from the Access Manager menu in the navigation bar.

    • Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.

    The Project Access Manager page displays.

2

Click Create Application Service Account.

3

Enter the service account information.

  1. Enter a Name.

  2. Enter a Description.

  3. Select a duration from the Client Secret Expiration menu.

  4. From the Project Permissions menu, select the new role or roles for the service account.

4

Click Create.

5

Copy and save the Client Secret.

The client secret acts as the password when creating access tokens.

Warning

This is the only time you can view the full client secret. Click Copy and save it to a secure location. Otherwise, you'll need to generate a new client secret.

6

Add an API Access List Entry.

  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 service account.

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

  3. Click Save.

You can use the Atlas Administration API to create a service account for your project.

After you've created the service account, copy and save the {CLIENT-ID} and {CLIENT-SECRET} from the output, which should look similar to the following example. This is the only time you can view the full client secret. You'll need this information when you make an API request.

{
  "createdAt" : "2024-04-23T17:47:17Z",
  "description" : "Service account for my organization.",
  "clientId" : "{CLIENT-ID}",
  "name" : "My Service Account",
  "roles" : [ "ORG_MEMBER" ],
  "secrets" : [ {
    "createdAt" : "2024-04-23T17:47:17Z",
    "expiresAt" : "2024-12-01T00:00:00Z",
    "id" : "6627f7259d39d858378c9e30",
    "lastUsedAt" : null,
    "secret" : "{CLIENT-SECRET}"
   } ]
}%

Make an API Request

The Atlas Administration API uses one of two authentication methods to authenticate requests: API keys or a service account. You'll need the keys or secret that you saved when configuring your preferred authentication method to complete the following procedures.

Important

Service accounts are currently in Preview. To learn more, see Service Accounts Overview.

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

To make an API request using a service account, use the service account to generate an access token, then use the access token in your request:

1

Retrieve the client secret for your service account.

Locate the client secret beginning with mdb_sa_sk_ that you saved immediately after creating the service account, which was the only time you could view the client secret. If you did not save the client secret, you must generate a new client secret.

2

Base64-encode the client ID and secret.

For example, run:

echo -n {CLIENT-ID}:{CLIENT-SECRET} | base64
3

Request an access token.

Replace {BASE64-AUTH} in the following example with the output from the preceding step, then run:

1curl --request POST \
2   --url https://cloud.mongodb.com/api/oauth/token \
3   --header 'accept: application/json' \
4   --header 'cache-control: no-cache' \
5   --header 'authorization: Basic {BASE64-AUTH}' \
6   --header 'content-type: application/x-www-form-urlencoded' \
7   --data 'grant_type=client_credentials'
{"access_token":"eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6ImYyZjE2YmE4LTkwYjUtNDRlZS1iMWYwLTRkNWE2OTllYzVhNyJ9.eyJpc3MiOiJodHRwczovL2Nsb3VkLWRldi5tb25nb2RiLmNvbSIsImF1ZCI6ImFwaTovL2FkbWluIiwic3ViIjoibWRiX3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImNpZCI6Im1kYl9zYV9pZF82NjI4MWJjNjAzYTcxYTQzMGI5MDZlZjciLCJhY3RvcklkIjoibWRiX3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImlhdCI6MTcxMzkwNTM1OSwiZXhwIjoxNzEzOTA4OTU5LCJqdGkiOiI4ZTg1MTM3YS0wZGU1LTQ0N2YtYTA0OS1hMmVmNTIwZGJhNTIifQ.AZSFvhcjwVcJYmvW6E_K5UnDmeiX2sJgL27vo5ElzeBuPawRciKkn6ervZ6IpUTx2HHllGgAAMmhaP9B66NywhfjAXC697X9KcOzm81DTtvDjLrFeRSc_3vFmeGvfUKKXljEdWBnbmwCwtBlO5SJuBxb1V5swAl-Sbq9Ymo4NbyepSnF","expires_in":3600,"token_type":"Bearer"}%

Important

The access token is valid for 1 hour (3600 seconds). You can't refresh an access token. When this access token expires, repeat this step to generate a new one.

4

Make an API call.

Replace {ACCESS-TOKEN} in the following example with the output from the preceding step.

The following sample GET request returns all projects in your organization:

curl --request GET \
     --url https://cloud.mongodb.com/api/atlas/v2/groups \
     --header 'Authorization: Bearer {ACCESS-TOKEN}' \
     --header 'Accept: application/vnd.atlas.2023-02-01+json' \
     --header 'Content-Type: application/json'

The following sample POST request takes a request body and creates a project named MyProject in your organization:

curl --header 'Authorization: Bearer {ACCESS-TOKEN}' \
      --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

In the MongoDB Atlas Administration API documentation, right-click the Download button and copy the link.

2

Open Postman and click File, then Import.

The Import window displays.

3

In the Import window, click Link and paste the download link that you copied in step 1.

4

Click Continue, then Import.

5

For the request for which you want to generate a curl command, click </> on the right and select cURL from the Code snippet dropdown.

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:

Back

Atlas Administration API

Next

Organization Access