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 administrative features in Atlas. To learn more about the Atlas Administration API, see Atlas Administration API Reference.
The Atlas Administration API doesn't provide access to the data stored in your clusters. To read or write data in a database, you must authenticate to your cluster using the credentials for a database user with the appropriate read or write roles. You can use the Atlas Administration API to create and manage database users.
To use the Atlas Administration API to manage your Atlas clusters, you must authenticate your API requests with one of the following authentication methods:
Service account access tokens (OAuth 2.0)
API keys (HTTP Digest Authentication)
To learn about these methods, see Atlas Administration API Authentication Methods.
The following sections describe how to use service accounts and API keys to configure programmatic access to your Atlas organizations and projects.
Required Access
To create a service account or API keys for an organization, you must have
Organization Owner access to that organization.
To grant a service account access to a project, you must have
Organization Owner access to the organization that owns the project.
To grant API keys access to a project, you must have
Project Owner access for that project.
Optional: Require an IP Access List for the Atlas Administration API
When you create an organization using the Atlas UI, Atlas enables the API IP access list feature by default. This limits API requests 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:
In Atlas, go to the Organization Settings page.
If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
In the sidebar, click Organization Settings.
The Organization Settings page displays.
Grant Programmatic Access to Atlas
You can grant programmatic access to an organization or project using one of the two following authentication methods:
Important
We recommend you use service accounts instead of API keys to authenticate to the Atlas Administration API. API keys are a legacy authentication method.
Service Account (Recommended) | API Keys (Legacy) |
|---|---|
New method of authenticating to Atlas using the industry standard OAuth 2.0 protocol with the Client Credentials flow. | Legacy method of authenticating to Atlas that uses HTTP Digest Authentication. |
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. | 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. |
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 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. |
Atlas roles limit which operations a service account can perform with its access token. You must assign roles to service accounts as you would for users to ensure that the service account generates access tokens with the necessary permissions for the desired API calls. | Atlas roles limit which operations API keys can perform. You must assign roles to API keys as you would for users to ensure the API keys have the necessary permissions for the desired API calls. |
Each service account belongs to only one organization, and can grant access to any number of projects in that organization. To give an organization-level service account access to a project, see Grant Existing Service Account Access to a Project. | Each pair of API keys belongs to only one organization, and can grant access to any number of projects in that organization. To give organization-level API keys access to a project, see Grant Existing Service Account Access to a Project. |
Atlas binds many resources to a project. Many API resource
URLs follow the format of | Atlas binds many resources to a project. Many API resource
URLs follow the format of |
You can't use a service account or its access token to log into Atlas through the Atlas UI. Service accounts only grant access to the Atlas Administration API, which does not include UI access or access to cluster data. | You can't use API keys to log into Atlas through the Atlas UI. API keys only grant access to the Atlas Administration API, which does not include UI access or access to cluster data. |
Grant Programmatic Access to an Organization
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 Methods.
Grant Programmatic Access to a Project
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 Methods.
Add Project Access from a Project
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.
Make an API Request
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 when configuring 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>
Important
MongoDB uses HTTPS URLs to increase security. Using HTTP URLs will return a 301 status code.
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.
Warning
Using an HTTP URL with Postman will return a 301 status code as expected. However, in this scenario, Postman may automatically retry the request with HTTPS, but simultaneously strip the header and body from the retry request. This will return a 401 status code instead of 301, making it difficult to determine why the request failed.
To use Postman to generate curl commands:
In the MongoDB Atlas Administration API documentation, right-click the Download button and copy the link.
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: