- API >
- Configure Atlas API Access
Configure Atlas API Access¶
On this page
To access the API, you must generate your own API key.
To access whitelisted API operations, you must configure your API
whitelist with the IP addresses you will use
when issuing the whitelisted commands. You also must have the Owner role
to issue whitelisted commands.
Important
For Atlas users with a non-empty API whitelist, all API access must originate from a whitelisted IP address. Ensure your configured whitelist entries provide appropriate coverage for all clients which require API access. An empty API whitelist grants access to all API endpoints except those that explicitly require whitelisting.
Atlas supports requiring API whitelisting at the organization level, such that any API activity for all projects within that organization must originate from an entry on each respective Atlas user’s API whitelist. For organizations that require API whitelisting, Atlas users cannot access any API operations until they define at least one API whitelist entry.
To require an API whitelist for an Organization:
- Log into Atlas.
- Access the Organization using the Context picker in the top-left hand corner of the Atlas UI.
- Click Settings from the left hand navigation.
- Toggle the Require IP Whitelist for Public API setting to On.
For a description of the Atlas API’s principles and conventions, see the API.
Generate API Keys¶
To access the Atlas API, you must generate an API key, which gives access to the API. Each user that will use the API must generate a key. You can have up to ten API keys associated with your account. Each key can be either enabled or disabled but all count toward the ten-key limit.
An API key is like a password. Keep it secret.
When accessing Atlas through the API, you have the same level of access as you do through the Atlas interface. Your Atlas roles apply to both the interface and the API.
Important
When you generate a key, Atlas displays it one time only. You must copy it. Atlas will never display the full key again.
On the upper-right hand corner, click on your user name and select Account. Click on Public API Access.
In the API Keys section, click Generate.
Type a description and click Generate.
If prompted for two-factor authentication, enter the code and click Verify. Then click Generate again.
Copy and record the key.
Copy the key immediately. Atlas displays the full key one time only. You will not be able to view the full key again.
Record the key in a secure place. After you record the key, click Close.
Provide Access to Whitelisted API Operations¶
Address-based whitelists protect API operations. Only client requests that originate from a whitelisted IP address are permitted to perform the operations.
Users have their own whitelists 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 whitelist. You cannot use your key to issue a whitelisted API request from an address on another user’s whitelist, unless, of course, you’ve added that address to your own whitelist.
On the resources pages in this guide, whitelisted operations are marked as such.
On the upper-right hand corner, click on your user name and select Account. Click on Public API Access.
In the API Whitelist section, click Add.
Enter an IP address or CIDR range. To add multiple entries to your whitelist, repeat this step. If you leave your whitelist empty, you have no access to whitelisted operations.
You can enter any of the following:
Entry Grants An IP address Access to whitelisted operations from that address. A CIDR-notated range of IP addresses Access to whitelisted operations from those addresses.
Delete an Address from the API Whitelist¶
- On the upper-right hand corner, click on your user name and select Account. Click on Public API Access.
- In the Whitelist section, click the address’s gear icon and select Delete.