Get Started with the Atlas Administration API
On this page
- Required for All Resources: Generate an Organization API Key
- Required for Select Resources: API Resource Request Access Lists
- Use API Resources that Require an Access List
- Require an API Access List for All Requests
- Grant Programmatic Access to Atlas
- Manage Programmatic Access to an Organization
- Manage Programmatic Access to a Project
- Manage Programmatic Access to Multiple Organizations
Important
Each Atlas Administration API has its own resources and requires initial setup. The Atlas Administration API and the App Services Admin API also use different access keys from the Data API.
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 APIs.
Required for All Resources: Generate an Organization API Key
To access the Atlas Administration API, Create an API Key in an Organization.
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.
To learn more about managing API keys for your organization or project, see Grant Programmatic Access to Atlas
Required for Select Resources: API Resource Request Access Lists
Atlas allows your API key to make requests from any address on the internet. Atlas has some exceptions to this rule. These exceptions limit which resources an API key can use without location-based limits defined in an API access list.
To add these location-based limits to your API key, create an API access list. This list limits the internet addresses from which a specific API key can make API requests.
Any API keys with an API access list require all API requests to come from an IP address on that list. Your API access list must include entries for all clients that use the API.
Use API Resources that Require an Access List
The following API resources require an API access list:
Organization API Access List Entries
Create or remove access list entries for an organization API key.
Cloud Backup Restores
Return a dedicated or serverless cloud backup restore job.
Return all dedicated or serverless cloud backup restore jobs.
Restore a dedicated or serverless cloud backup snapshot.
Cancel the restore of a dedicated or serverless cloud backup snapshot.
Cloud Backup Snapshots
Take or remove one replica set or sharded cluster cloud backup snapshot.
Cloud Backup Schedules
Return the cloud backup schedule for an Atlas cluster.
Create or modify the cloud backup schedule for an Atlas cluster.
Legacy Backups
Restore, remove, or change the expiration date of a legacy backup snapshot.
Require an API Access List for All Requests
You can require all API requests from an API key to come from an entry on its API access list. If you require API access lists, API keys can't make any API requests until you define at least one API access list entry.
Procedure
To set your organization to require API access lists for every API key:
Log in to Atlas.
Navigate to the Settings page for your organization.
If it is not already displayed, select your desired organization from the Organizations menu in the navigation bar.
Click the Organization Settings icon next to the Organizations menu.
Toggle the Require IP Access List for the Atlas Administration API setting to On.
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.
Each API key belongs to only one organization, but you can grant an API key access to any number of projects in that organization.
Manage Programmatic Access to an Organization
Note
Required Permissions
To perform any of the following actions, you must have the
Organization Owner role.
Create an API Key in an Organization
View API Keys in an Organization
Change an API Key in an Organization
Delete an API Key from an Organization
Manage Programmatic Access to a Project
Note
Required Permissions
To perform any of the following actions, you must have the
Project Owner role.
Note
Requires Access List
To make this API request:
Configure an IP access list.
Add the IP addresses or CIDR blocks of your client applications to the access list using the console or API. If you host your application on AWS, you can use an AWS security group ID as well.
Changing an API key's access list might impact multiple organizations, projects, or both.
Invite an Organization API Key to a Project
Create an API Key for a Project
View the API Keys in a Project
Change an API Key's Roles in a Project
Navigate to the Access Manager page for your project.
If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
Select your desired project from the list of projects in the Projects page.
Click the vertical ellipsis () next to your project name in the upper left corner and select Project Settings.
Click Access Manager in the navigation bar, then click your project.
Click the API Keys tab.
Edit the Access List.
Click to the right of the API Key.
Click Edit Permissions.
Select the new role or roles for the API Key from the Project Permissions menu.
Click the to save.
Edit an API Key's Access List
Delete an API Key from a Project
Manage Programmatic Access to Multiple Organizations
Note
Required Permissions
To perform any of the following actions, you must have the
Organization Owner role.
In the organizations and projects hierarchy, an organization can contain multiple projects (previously referred to as groups). Under this structure:
Billing happens at the organization level while preserving visibility into usage in each project.
You can view all projects within an organization.
You can use teams to bulk assign organization users to projects within the organization.
If you need to scale beyond the existing project limits, you can create multiple organizations.
Create Multiple Organizations
Repeat the following steps to create multiple organizations:
View all of your organizations.
Expand the Organizations menu in the navigation bar.
Click View All Organizations.
Click New Organization.
Enter the name for your organization.
Select Atlas and click Next.
You have the option of adding a new Cloud Manager organization or a new Atlas organization. For more information on Cloud Manager see the documentation.
Add members.
For existing Atlas users, enter their username. Usually, this is the email the person used to register.
For new Atlas users, enter their email address to send an invitation.
Specify the access for the members.
Click Create Organization.
(Optional) Set Up Cross-Organization Billing
You can set up cross-organization billing to share a billing subscription across multiple organizations.
The following prerequisites and limitations apply:
To link a paying organization to another organization, you must have
Organization Billing AdminorOrganization Ownerprivileges for both organizations.A paying organization and any linked organizations must be on the same subscription plan.
A paying organization and any linked organizations must have the same minimums, uplifts, and SLA for their subscription plan.
A paying organization and any linked organizations can't have overlapping monthly commitment deals.
A paying organization on a prepaid subscription plan and any linked organizations must be on the same current and future subscription plans.
You can use the Atlas UI to manually link a paying organization to a maximum of 20 other organizations. To link a paying organization to more than 20 other organizations, contact support.
A paying organization can't link more than 100 other organizations.
A paying organization can't already be a linked organization.
A paying organization must have an Atlas subscription.
Note
To purchase a subscription that enables cross-organization billing, contact MongoDB Sales.
To configure a paying organization and link other organizations to it:
Select an organization to configure as a paying organization.
If it is not already displayed, select your desired organization from the Organizations menu in the navigation bar. If you wish to create a new organization through which to pay, Create an Organization first.
Click Billing.
Click Billing in the top navigation bar or in the left navigation panel.
Click the Linked Organizations tab.
Note
The Linked Organizations tab only displays if your selected organization is eligible to be a paying organization for cross-organization billing.
Start linking.
If you are configuring a new paying organization, click Start Linking.
If your organization is already a paying organization, click Link More Organizations.
Select organizations to link to your paying organization.
A dialog displays your selected organization under Paying organization on the left and a list of organizations you may link to it under Select organizations to link on the right.
Select each organization you wish to link to your paying organization.
Click Review and Finish.
Review and finalize your links.
Important
After you click Finish, you will not be able to unlink organizations unless you contact Support.
Confirm that your organizations are linked as intended and click Finish.
Create API Keys for your Organizations
To manage projects in all your organizations:
Create an API for each organization.
Repeat the steps to create an API key for an organization for each organization.
Invite the organization key to each project within the organization.
For each project within an organization, invite the related organization key.