Navigation
This version of the documentation is archived and no longer supported. To learn how to upgrade your version of MongoDB Ops Manager, refer to the upgrade documentation.
You were redirected from a different version of the documentation. Click here to go back.
This version of the manual is no longer supported.
  • API >
  • Configure Public API Access

Configure Public API Access

To access the Ops Manager API, you must generate an API key for either programmatic access for an organization or a Personal API Key (deprecated) for an Ops Manager user.

Preferred Method to Use API

MongoDB recommends using Programmatic API Keys instead of Personal API Keys (deprecated).

API Keys cannot use the Ops Manager User Interface

API keys that are associated with an organization are not associated with user credentials and cannot log in to the MongoDB Atlas user interface.

Prerequisite

Enable API Whitelisting for Your Organization

For Ops Manager users with a non-empty API whitelist, all API access must originate from a whitelisted IPv4 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.

Ops Manager 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 Ops Manager user’s API whitelist. For organizations that require API whitelisting, Ops Manager users cannot access any API operations until they define at least one API whitelist entry.

To require an API whitelist for an Organization:

  1. Log into Ops Manager.
  2. Access the Organization using the Context picker in the top-left hand corner of the Ops Manager UI.
  3. Click Settings from the left hand navigation.
  4. Toggle the Require IP Whitelist for Public API setting to On.

Programmatic API Keys

To grant programmatic access to an organization or project using only the API, you can create an API key. API Keys:

  • Have two parts: a Public Key and a Private Key.

    These serve the same function as a username and Personal API Key when making API requests to MongoDB Atlas.

  • Cannot be used to log into MongoDB Atlas through the user interface.

  • Must be granted roles as you would Users to make sure the API Keys can call API endpoints without errors.

  • Can belong to one organization, but may be granted access to any number of projects in that organization.

Programmatic API Keys can be set globally through the API Key page in the Admin interface.

Manage Programmatic Access to an Organization

Required Permissions

To perform any of the following actions, you must have the Organization Owner role.

Create an API Key in an Organization

  1. From the Context menu, select the organization that you want to view.

  2. Click Access.

  3. Click the tab for API Keys.

  4. Select Create API Key from the Manage button menu.

  5. From the API Key Information step of the Add API Key page, enter a description for the new API Key in the Description box.

  6. Select the new role or roles for the API Key from the Organization Permissions menu.

  7. Click Next.

  8. From the Private Key & Whitelist step of the Add API Key page, click Add Whitelist Entry.

  9. Enter an IPv4 address from which you want Ops Manager to accept API requests for this API Key.

    You can also click Use Current IP Address if the host you are using to access Ops Manager also will make API requests using this API Key.

  10. Click Save.

    Copy the Private Key Before Leaving this Page

    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 this Private Key as you would any other password.

View the Details of an API Key in an Organization

  1. From the Context menu, select the organization that you want to view.

  2. Click Access.

  3. Click the tab for API Keys to see the available keys.

  4. From the ellipsis menu 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 IPv4 addresses on which the key is whitelisted
    • The projects to which the Key has been granted access

Change an API Key in an Organization

You can change the roles, description, or whitelist of an API Key in an Organization.

  1. From the Context menu, select the organization that you want to view.

  2. Click Access.

  3. Click the tab for API Keys to see the available keys.

  4. From the ellipsis menu to the right of the API Key you want to change, click Edit.

  5. From the API Key Information step of the Add API Key page, you can change the description of the API Key in the Description box.

  6. You can change existing or add new roles to the API Key from the Organization Permissions menu.

  7. Click Next.

  8. From the Private Key & Whitelist step of the Add API Key page, you can add or remove an IP address to the whitelist.

    • To add an IP address from which you want Ops Manager to accept API requests for this API Key, click Add Whitelist Entry and type an IPv4 address.

      You can also click Use Current IP Address if the host you are using to access Ops Manager also will make API requests using this API Key.

    • To remove a whitelisted IP address, click trash icon to the right of the whitelisted IP address.

  9. Click Save.

Delete an API Key from an Organization

  1. From the Context menu, select the organization that you want to view.

  2. Click Access.

  3. Click the tab for API Keys to see the available keys.

  4. Click trash icon to the right of the API Key that you want to delete.

  5. 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 a Project

Required Permissions

To perform any of the following actions, you must have either the Project User Admin role.

Create an API Key for a Project

  1. From the Context menu, select the project that you want to view.

  2. Click Access.

  3. Click the tab for API Keys.

  4. Select Create API Key from the Manage button menu.

  5. From the API Key Information step of the Add API Key page, enter a description for the new API Key in the Description box.

  6. Select the new role or roles for the API Key from the Project Permissions menu.

  7. Click Next.

  8. From the Private Key & Whitelist step of the Add API Key page, click Add Whitelist Entry.

  9. Enter an IPv4 address from which you want Ops Manager to accept API requests for this API Key.

    You can also click Use Current IP Address if the host you are using to access Ops Manager also will make API requests using this API Key.

  10. Click Save.

    Copy the Private Key Before Leaving this Page

    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 this Private Key as you would any other password.

View the Details of an API Key in a Project

  1. From the Context menu, select the project that you want to view.

  2. Click Access.

  3. Click the tab for API Keys to see the available keys.

  4. From the ellipsis menu 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 it was created, and the IPv4 addresses on which the key is whitelisted.

Change an API Key’s Roles in a Project

  1. From the Context menu, select the project that you want to view.
  2. Click Access.
  3. Click the tab for API Keys to see the available keys.
  4. From the ellipsis menu to the right of the API Key, click Edit Permissions.
  5. Select the new role or roles for the API Key from the menu.
  6. Click on the checkmark to save.

Delete an API Key from a Project

  1. From the Context menu, select the project that you want to view.
  2. Click Access.
  3. Click the tab for API Keys to see the available keys.
  4. Click trash icon to the right of the API Key.

Personal API Keys (Deprecated)

Important

Personal API keys are deprecated, use Programmatic API Keys instead.

Each user can have up to 10 API keys associated with their account. Each key can be either enabled or disabled but all count toward the 10 key limit.

An API key is like a password. Keep it secret.

Access Control

Your Ops Manager roles determine which API resources you can use. Your Ops Manager roles apply to both the interface and the API.

Limit API Operations to Whitelisted IPv4 Addresses

To access whitelisted API operations, you must configure your API whitelist with the IPv4 addresses from which you will issue the whitelisted commands. You also must have the Organization Owner role to issue whitelisted commands.

Address-based whitelists protect API operations. Only client requests that originate from a whitelisted IPv4 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.

Add an IPv4 Address to the API Whitelist

1

Click on your user name in the upper-right hand corner and select Account. Click Public API Access.

2

In the Whitelist, click Add and enter an address.

Enter an IP address or CIDR range. To add multiple entries in the whitelist, repeat this step.

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.

If you leave the whitelist empty, you have no access to whitelisted operations.

Delete an IPv4 Address from the API Whitelist

1

Go to your Public API Access view.

Click on your user name in the upper-right hand corner and select Account. Then click Public API Access.

2

In the Whitelist, select the gear icon for the address and select Delete.