Configure Atlas API Access¶
To access the Atlas API , generate an API key for your organization.
- You cannot create new Personal API Keys.
- You cannot use your existing Personal API Keys to access the API from March 1, 2021.
- You must update any existing scripts or tools to use Programmatic API Keys instead.
Organization API keys aren't associated with user credentials and can't log in to the Atlas console.
Prerequisite¶
Enable the API Access List for Your Organization¶
For Atlas users with a non-empty API access list, all API access must originate from an IP address on an API access list. Configure your access list entries to include all clients which require API access. An empty API access list grants access to all API endpoints except those that explicitly require an API access list.
You can configure Atlas to require API access listing at the organization level. When this setting is enabled, all API calls within that organization must originate from an entry on each respective Atlas user’s API access list. For organizations that require API access listing, Atlas users cannot access any API operations until they define at least one API access list entry.
To require an API access list for an Organization:
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 Public API setting to On.¶
For a description of the Atlas API 's principles and conventions, see the API.
Programmatic API Keys¶
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. You can't use an API key to log into Atlas through the user interface.
All API keys belong to the organization, but can be given access to a project.
To create and manage API keys, use the Access Manager.
When you create a new API key, Atlas grants key the following permissions:
Organization | Organization Member |
---|---|
Project |
You can add more permissions to the new API key when you create it.
To add the new API key created in an organization, invite the API key to the project.
Manage Programmatic Access to One Organization¶
To perform any of the following actions, you must have the
Organization Owner
role.
Create One API Key in One Organization¶
Navigate to the Access Manager page for your organization.¶
- If it is not already displayed, select your desired organization from the Organizations menu in the navigation bar.
- Click Access Manager in the sidebar, or click Access Manager in the navigation bar, then click your organization.
Click the API Keys tab.¶
Create an API Key.¶
- Click Manage.
- Select Create API Key.
Enter the API Key Information.¶
- Navigate to the Add API Key page.
- Enter a Description.
- In the Organization Permissions menu, select the new role or roles for the API key.
Copy and save the Public Key.¶
The public key acts as the username when making API requests.
Click Next.¶
Copy and save the Private Key.¶
The private key acts as the password when making API requests.
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.
Add an API Access List Entry.¶
- Click Add Access list Entry.
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 also will make API requests using this API Key.
- Click Save.
Click Done.¶
View the Details of One API Key in One Organization¶
Navigate to the Access Manager page for your organization.¶
- If it is not already displayed, select your desired organization from the Organizations menu in the navigation bar.
- Click Access Manager in the sidebar, or click Access Manager in the navigation bar, then click your organization.
Click the API Keys tab.¶
View the Access List.¶
- Click to the right of the API Key.
- Click View Details.
The <Public Key> API Key Details modal displays:
- The obfuscated Private Key
- The date the Key was last used
- The date the Key was created
- The IP addresses from which the Key can access the API
- The projects to which the Key has been granted access
Change One API Key in One Organization¶
You can change the roles, description, or access list of an API Key in an Organization.
Navigate to the Access Manager page for your organization.¶
- If it is not already displayed, select your desired organization from the Organizations menu in the navigation bar.
- Click Access Manager in the sidebar, or click Access Manager in the navigation bar, then click your organization.
Click the API Keys tab.¶
From the ellipsis menu to the right of the API Key you want to change, click Edit.¶
Edit the API Key Information.¶
On the Add API Key page:
- Modify the Description.
- In the Organization Permissions menu, select the new role or roles for the API key.
Click Next.¶
Edit the API Access List.¶
To add an IP address or CIDR block from which you want Atlas to accept API requests for this API Key, click Add Access list Entry and type an IP address.
You can also click Use Current IP Address if the host you are using to access Atlas also will make API requests using this API Key.
- To remove an IP address from the access list, click to the right of the IP address.
- Click Save.
Click Done.¶
Delete an API Key from One Organization¶
Navigate to the Access Manager page for your organization.¶
- If it is not already displayed, select your desired organization from the Organizations menu in the navigation bar.
- Click Access Manager in the sidebar, or click Access Manager in the navigation bar, then click your organization.
Click the API Keys tab.¶
Click to the right of the API Key that you want to delete.¶
Click Delete to confirm that you want to delete this API Key or Cancel to leave the key in the Organization.¶
Removing an API Key from an Organization also removes that key from any projects to which the key was granted access.
Manage Programmatic Access to One Project¶
To perform any of the following actions, you must have the
Project Owner
role.
Create One API Key for One 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.¶
Create an API Key.¶
- Click Manage.
- Select Create API Key.
Enter the API Key Information.¶
On the Add API Key page:
- Enter a Description.
- In the Project Permissions menu, select the new role or roles for the API key.
Copy and save the Public Key.¶
The public key acts as the username when making API requests.
Click Next.¶
Copy and save the Private Key.¶
The private key acts as the password when making API requests.
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.
Add an API Access List Entry.¶
- Click Add Access list Entry.
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 also will make API requests using this API Key.
- Click Save.
Click Done.¶
Invite One Organization API Key to One 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.¶
Add the API Key to the project.¶
- Click Invite to Project.
- Type the public key into the field.
- In the Project Permissions menu, select the new role or roles for the API key.
Click Invite to Project.¶
View the Details of One API Key in One 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.¶
View the Access List.¶
- Click to the right of the API Key.
- Click View Details.
The <Public Key> API Key Details modal displays the following information:
- The obfuscated Private Key
- The date the key was last used
- The date the key was created
- The IP address or addresses from which the API key can access the API
Change One API Key's Permissions in One 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 One API Key's Access List¶
To edit a project API key's access list, you must have the
Organization Owner
permission. Changing an API key's
access list might impact multiple projects.
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.
Selecting Edit Permissions takes you to the organization level of the Atlas console.
Edit the API Access List.¶
You cannot modify an existing API Key access list entry. You must delete and re-create it.
- Click to the right of the IP address to remove it.
Add the new IP address from which you want Atlas to accept API requests for this API Key. Use one of the two options:
- Click Add access list Entry and type an IP address, or
- Click Use Current IP Address if the host you are using to access Atlas will also make API requests using this API Key.
- Click Save.
Click Done.¶
Delete One API Key from One 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.¶
Click to the right of the API Key that you want to delete.¶
Click Delete to confirm that you want to delete this API Key or Cancel to leave the key in the project.¶
Personal API Keys (Deprecated)¶
- You cannot create new Personal API Keys.
- You cannot use your existing Personal API Keys for accessing the API from March 1, 2021.
- You must update any existing scripts or tools to use Programmatic API Keys instead.
You can no longer create Personal API Keys. You can manage any Personal API Keys that you have currently.
To manage any existing personal API keys:
Navigate to the Personalization page.¶
- In the upper right corner of the Atlas UI, click your username to access the Account menu.
- Under Atlas, click User Preferences.
In the sidebar, click Public API Access.¶
When accessing Atlas through the API , you have the same level of access as you do through the Atlas interface. Your Atlas permissions apply to both the interface and the API .
Limit API Operations to Permitted IP Addresses¶
To access API operations limited to an API access list:
- Configure your API access list with the IP addresses from which you will issue the whitelisted commands.
- Grant your API key the
Organization Owner
permission to issue whitelisted commands.
Address-based access lists protect API operations. Only client requests that originate from a whitelisted IP address are permitted to perform the operations.
Users have their own access lists and own API keys. When you issue an API call, you must use an API key from your user account and must issue the command from an address on your user account's access list. You cannot use your key to issue a whitelisted API request from an address on another user's access list, unless, of course, you've added that address to your own access list.
On the resources pages in this guide, whitelisted operations are marked as such.
Add an IPv4 Address to the API Whitelist¶
Navigate to the Personalization page.¶
- In the upper right corner of the Atlas UI, click your username to access the Account menu.
- Under Atlas, click User Preferences.
In the sidebar, click Public API Access.¶
Add entries to the API access list.¶
- In the Personal API Key Access List section, click Add.
Enter an IP address or CIDR range. To add multiple entries to your access list, repeat this step. If you leave your access list empty, you have no access to protected operations.
You can enter any of the following:
Entry Grants An IP address Access to protected operations from that address. A CIDR