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
When you create an organization using the Atlas UI, Atlas automatically requires enables an IP access list for the Atlas Administration API. 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 this 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.
Note
IP access lists apply to using service account access tokens, not creating or revoking them. You can generate a token from any IP address, but you can only use it to call the API if your IP address is on the access list.
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 an Organization
Grant Programmatic Access to a Project
To learn more about these two authentication methods, see Atlas Administration API Authentication Methods.
To give API keys access to a project, you must have
Project Access Manager or Project Owner
access for that project.
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, click Download source in the navigation bar.
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: