Get Started with the Atlas Administration API (original) (raw)

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 orprivate endpoints.

To learn more, see Atlas Programmatic Access.

The Atlas Administration API follows the principles of the RESTarchitectural style to expose a number of internal resources which enable programmatic access to Atlas's features. To learn more, seeAtlas Administration API Reference.

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

When you create an organization using the Atlas UI, Atlasenables the API IP access list feature by default. This limits APIrequests to only those from the location-based IP or CIDR addresses that you specify in the IP access list. If you make a request to the Atlas Administration API without an IP access list entry, the server responds with a 403 status code.

If you disable the feature, you can make API requests from any address on the internet as long as the IP access list is empty. Once you add an IP access list entry, only requests originating from that IP address can make requests.

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

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

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 theOrganizations menu.
   The Organization Settingspage displays.

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

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

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

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 theAccess Manager menu in the navigation bar.
   • Click Access Manager in the sidebar.
     The Organization Access Manager page displays.

3. Enter a Name.

4. Enter a Description.

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

6. From the Organization Permissions menu, select thenew role or roles for the service account.

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

Warning

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

1. Click Add Access List Entry.
2. Enter an IP address or CIDR block from which you want Atlasto 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}"

   } ]

}%

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.

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.

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

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 theAccess Manager menu in the navigation bar.
   • Click Access Manager in the sidebar.
     The Organization Access Manager page displays.

3. Enter a Description.

4. In the Organization Permissions menu, select thenew role or roles for theAPI key.

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

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.

1. Click Add Access list Entry.
2. Enter an IP address or CIDR block from which you want Atlasto 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.

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

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

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

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

Warning

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

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

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 theAccess Manager menu in the navigation bar.
   • Next to the Projects menu, expand the Options menu, clickProject Settings, and clickAccess Manager in the sidebar.
     The Project Access Manager page displays.

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

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:

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

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 theAccess Manager menu in the navigation bar.
   • Next to the Projects menu, expand the Options menu, clickProject Settings, and clickAccess Manager in the sidebar.
     The Project Access Manager page displays.

4. Type the public key into the field.

5. In the Project Permissions menu, select thenew role or roles for theAPI key.

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

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

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

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 theAccess Manager menu in the navigation bar.
   • Next to the Projects menu, expand the Options menu, clickProject Settings, and clickAccess Manager in the sidebar.
     The Project Access Manager page displays.

4. Enter a Name.

5. Enter a Description.

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

7. From the Project Permissions menu, select thenew role or roles for the service account.

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

Warning

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

1. Click Add Access List Entry.
2. Enter an IP address or CIDR block from which you want Atlasto 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}"

   } ]

}%

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

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

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

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 theAccess Manager menu in the navigation bar.
   • Next to the Projects menu, expand the Options menu, clickProject Settings, and clickAccess Manager in the sidebar.
     The Project Access Manager page displays.

On the Create API Key page:

1. Enter a Description.
2. In the Project Permissions menu, select thenew role or roles for the API key.

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

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.

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.

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

All Atlas Administration API endpoints have the following base URL:

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

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:

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.

For example, run:

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

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

1

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

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

The following sample GET requestreturns 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 andcreates a project namedMyProject 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"

         }'

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'sPostman workspace.

The following sample GET requestreturns 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 andcreates a project namedMyProject 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"

         }'

See also:

• Atlas Administration API Specification
• Atlas Administration API Error Codes

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 Specificationinto Postman to generate curlcommands. To use Postman to generate curl commands:

The Import window displays.

To learn more about the Atlas Administration API, seeAtlas 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.
• Rotate Service Account Secrets.