Programmatic Access to Cloud Manager

On this page

Manage Programmatic Access to an Organization

Manage Programmatic Access to a Project
Make an API Request

Cloud Manager will no longer support Automation, Backup, and Monitoring for MongoDB 3.6 and 4.0 after August 30th, 2024. Please upgrade your MongoDB deployment or migrate to Atlas.

OAuth 2.0 authentication for programmatic access to Cloud Manager is available as a Preview feature.: The feature and the corresponding documentation might change at any time during the Preview period. To use OAuth 2.0 authentication, create a service account to use in your requests to the Cloud Manager Public API.

To grant programmatic access to an organization or project using only the API, create an API key or a service account. This ensures that the keys and access tokens that serve as usernames and passwords are never sent over the network. API keys and service accounts:

Can't be used to log into Cloud Manager through the UI.
Must be granted roles as you would users to make sure the API keys and sevice accounts can call API endpoints without errors.
Belong to one organization, but can be granted access to any number of projects in that organization.

To learn more about these two authentication methods, see Authentication.

Manage Programmatic Access to an Organization

Note

Required Permissions

You can view programmatic access to an organization with any role.

To perform any other action, you must have the Organization Owner role.

Grant Programmatic Access to an Organization

Use the following procedures to grant programmatic access to an organization either through API keys or a service account. To learn more about these two authentication methods, see Authentication.

In MongoDB Cloud Manager, go to the Organization Settings page.

If it's 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.
The Organization Settings page displays.

Go to the Organization Access Manager page.

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

Click Add new Application API Key.

Complete the API Key Information form.

From the API Key Information step of the Add API Key page:

Field	Value
Description	Enter a description for the new API Key.
Organization Permissions	Select the new role or roles for the API Key.

Click Next.

Add Access List Values for this API Key.

From the Private Key & Access List step of the Add API Key page, click Add Access List Entry.

For this API Key, You can choose to either:

Enter an IPv4 address from which Cloud Manager should accept API requests, or
Click Use Current IP Address if the host you are using to access Cloud Manager will make API requests.

Click Save.

Warning

Copy the Private Key Before Leaving this Page

Cloud Manager displays the Private Key once: on this page. Click Copy to add the Private Key to the clipboard. Save and secure this Private Key as you would any other password.

In MongoDB Cloud Manager, go to the Organization Settings page.

If it's 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.
The Organization Settings page displays.

Go to the Organization Access Manager page.

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

Click Add new Application Service Account.

Enter the service account information.

Enter a Name.
Enter a Description.
Select a duration from the Client Secret Expiration menu.
From the Organization Permissions menu, select the new role or roles for the service account.

Click Create.

Copy and save the Client Secret.

The client secret acts as the password when creating access tokens.

Warning

This is the only time you can view the full client secret. Click Copy and save it to a secure location. Otherwise, you'll need to generate a new client secret.

Add an API Access List Entry.

Click Add Access List Entry.
Enter an IP address or CIDR block from which you want Cloud Manager to accept API requests for this service account.
You can also click Use Current IP Address if the host you are using to access Cloud Manager will also make API requests using this service account.
Click Save.

View Programmatic Access to an Organization

You can view the details of all API keys or service accounts that have access to your organization.

In MongoDB Cloud Manager, go to the Organization Settings page.

If it's 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.
The Organization Settings page displays.

Go to the Organization Access Manager page.

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

Click the Applications tab.

Click API Keys.

Navigate to View Details.

Next to the API Key, click .
Click View Details.
The <Public Key> API Key Details modal displays the:
- Obfuscated Private Key.
- Date the Key was last used.
- Date the Key was created.
- IPv4 addresses on which the key is in the access list.
- Projects to which the Key has been granted access.

In MongoDB Cloud Manager, go to the Organization Settings page.

If it's 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.
The Organization Settings page displays.

Go to the Organization Access Manager page.

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

Click the Applications tab.

Click Service Accounts.

All the service accounts with access to your organization are listed.

Click the name of a service account to view its details, including:

The obfuscated client secret for the service account
The date the client secret was last used
The date the client secret was created
The IP addresses from which the service account can access the API
The roles the service account has been assigned

Update Programmatic Access to an Organization

You can change the roles, description, or access list of an API key or service account in an organization. You can also generate a new client secret for a service account.

In MongoDB Cloud Manager, go to the Organization Settings page.

If it's 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.
The Organization Settings page displays.

Go to the Organization Access Manager page.

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

Click the Applications tab.

Click API Keys.

Select the API Key to edit.

Click the next to the API Key you want to change.
Click Edit.

Complete the API Key Information form.

From the API Key Information step of the Add API Key page:

Field	Value
Description	Enter a description for the new API Key.
Organization Permissions	Select the new role or roles for the API Key.

Click Next.

Add Access List Values for this API Key.

From the Private Key & Access List step of the Add API Key page, click Add Access List Entry.

For this API Key, You can choose to either:

Enter an IPv4 address from which Cloud Manager should accept API requests, or
Click Use Current IP Address if the host you are using to access Cloud Manager will make API requests.

Click Save.

Warning

Copy the Private Key Before Leaving this Page

Cloud Manager displays the Private Key once: on this page. Click Copy to add the Private Key to the clipboard. Save and secure this Private Key as you would any other password.

In MongoDB Cloud Manager, go to the Organization Settings page.

If it's 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.
The Organization Settings page displays.

Go to the Organization Access Manager page.

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

Click the Applications tab.

Click Service Accounts.

Click the name of a service account.

Edit the Service Account Info.

To modify the Name or Description, click .

Generate a new client secret.

Click Generate New Client Secret
Choose a duration for the client secret from the menu. The client secret expires after this duration.
Click Generate New.
Click Copy and save the client secret to a secure location. This is the only time you can view the full client secret.

Edit the Organization Permissions.

Click Edit Permissions.
From the Organization Permissions menu, select the new role or roles for the service account.
Click Save and next.
Important
The service account credentials remain active until they expire or a user revokes them.

Edit the API Access List.

To add an IP address or CIDR block from which you want Cloud Manager to accept API requests for this service account, 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 Cloud Manager also will make API requests using this service account.
To remove an IP address from the access list, click to the right of the IP address.
Click Save.

Revoke Programmatic Access to an Organization

In MongoDB Cloud Manager, go to the Organization Settings page.

If it's 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.
The Organization Settings page displays.

Go to the Organization Access Manager page.

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

Click the Applications tab.

Click API Keys.

Delete the API Key.

Click next to 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.

Note

Removing an API Key from an Organization also removes that key from any projects to which the key was granted access.

In MongoDB Cloud Manager, go to the Organization Settings page.

If it's 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.
The Organization Settings page displays.

Go to the Organization Access Manager page.

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

Click the Applications tab.

Click Service Accounts.

Delete the service account.

Click the icon under Actions to the right of the service account you want to delete.
Click Delete.

Deleting a service account from an organization also removes it from from any projects to which the service account was granted access.

Manage Programmatic Access to a Project

Note

Required Permissions

You can view programmatic access to a project with any role.

To perform any other action, you must have the Project User Admin role.

Grant Programmatic Access to a Project

Use the following procedures to grant programmatic access to a project either through API keys or a service account. To learn more about these two authentication methods, see Authentication.

In MongoDB Cloud Manager, go to the Project Access Manager page.

If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Do one of the following steps:
- Select Project Access from the Access Manager menu in the navigation bar.
- Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.
The Project Access Manager page displays.

Click Create Application API Key.

Complete the API Key Information form.

From the API Key Information step of the Add API Key page:

Field	Value
Description	Enter a description for the new API Key.
Project Permissions	Select the new role or roles for the API Key.

Click Next.

Add Access List Values for this API Key.

From the Private Key & Access List step of the Add API Key page, click Add Access List Entry.

For this API Key, You can choose to either:

Enter an IPv4 address from which Cloud Manager should accept API requests, or
Click Use Current IP Address if the host you are using to access Cloud Manager will make API requests.

Click Save.

Warning

Copy the Private Key Before Leaving this Page

Cloud Manager displays the Private Key once: on this page. Click Copy to add the Private Key to the clipboard. Save and secure this Private Key as you would any other password.

In MongoDB Cloud Manager, go to the Project Access Manager page.

If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Do one of the following steps:
- Select Project Access from the Access Manager menu in the navigation bar.
- Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.
The Project Access Manager page displays.

Click Create Application Service Account.

Enter the service account information.

Enter a Name.
Enter a Description.
Select a duration from the Client Secret Expiration menu.
From the Project Permissions menu, select the new role or roles for the service account.

Click Create.

Copy and save the Client Secret.

The client secret acts as the password when creating access tokens.

Warning

This is the only time you can view the full client secret. Click Copy and save it to a secure location. Otherwise, you'll need to generate a new client secret.

Add an API Access List Entry.

Click Add Access List Entry.
Enter an IP address or CIDR block from which you want Cloud Manager to accept API requests for this service account.
You can also click Use Current IP Address if the host you are using to access Cloud Manager will also make API requests using this service account.
Click Save.

View Programmatic Access to a Project

You can view the details of all API keys or service accounts that have access to your project.

In MongoDB Cloud Manager, go to the Project Access Manager page.

If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Do one of the following steps:
- Select Project Access from the Access Manager menu in the navigation bar.
- Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.
The Project Access Manager page displays.

Click the Applications tab.

Click API Keys.

Navigate to View Details.

Next to the API Key, click .
Click View Details.
The <Public Key> API Key Details modal displays the:
- Obfuscated Private Key.
- Date the Key was last used.
- Date the Key was created.
- IPv4 addresses on which the key is in the access list.
- Projects to which the Key has been granted access.

In MongoDB Cloud Manager, go to the Project Access Manager page.

If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Do one of the following steps:
- Select Project Access from the Access Manager menu in the navigation bar.
- Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.
The Project Access Manager page displays.

Click the Applications tab.

Click Service Accounts.

All the service accounts with access to your project are listed.

Click the name of a service account to view its details, including:

The obfuscated client secret for the service account
The date the client secret was last used
The date the client secret was created
The IP addresses from which the service account can access the API
The roles the service account has been assigned

Update Programmatic Access to a Project

In MongoDB Cloud Manager, go to the Project Access Manager page.

If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Do one of the following steps:
- Select Project Access from the Access Manager menu in the navigation bar.
- Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.
The Project Access Manager page displays.

Click the Applications tab.

Click API Keys.

Select the API Key to edit.

Click the next to the API Key you want to change.
Click Edit.

Complete the API Key Information form.

From the API Key Information step of the Add API Key page:

Field	Value
Description	Enter a description for the new API Key.
Project Permissions	Select the new role or roles for the API Key.

Click Next.

Add Access List Values for this API Key.

From the Private Key & Access List step of the Add API Key page, click Add Access List Entry.

For this API Key, You can choose to either:

Enter an IPv4 address from which Cloud Manager should accept API requests, or
Click Use Current IP Address if the host you are using to access Cloud Manager will make API requests.

Click Save.

Warning

Copy the Private Key Before Leaving this Page

Cloud Manager displays the Private Key once: on this page. Click Copy to add the Private Key to the clipboard. Save and secure this Private Key as you would any other password.

In MongoDB Cloud Manager, go to the Project Access Manager page.

If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Do one of the following steps:
- Select Project Access from the Access Manager menu in the navigation bar.
- Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.
The Project Access Manager page displays.

Click the Applications tab.

Click Service Accounts.

Click the name of a service account.

Edit the Service Account Info.

To modify the Name or Description, click .

Generate a new client secret.

Click Generate New Client Secret
Choose a duration for the client secret from the menu. The client secret expires after this duration.
Click Generate New.
Click Copy and save the client secret to a secure location. This is the only time you can view the full client secret.

Edit the Project Permissions.

Click Edit Permissions.
From the Project Permissions menu, select the new role or roles for the service account.
Click Save and next.
Important
The service account credentials remain active until they expire or a user revokes them.

Edit the API Access List.

To add an IP address or CIDR block from which you want Cloud Manager to accept API requests for this service account, 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 Cloud Manager also will make API requests using this service account.
To remove an IP address from the access list, click to the right of the IP address.
Click Save.

Revoke Programmatic Access to a Project

In MongoDB Cloud Manager, go to the Project Access Manager page.

If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Do one of the following steps:
- Select Project Access from the Access Manager menu in the navigation bar.
- Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.
The Project Access Manager page displays.

Click the API Keys tab.

Delete the API Key.

Click next to 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.

Note

Removing an API Key from an Organization also removes that key from any projects to which the key was granted access.

In MongoDB Cloud Manager, go to the Project Access Manager page.

If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Do one of the following steps:
- Select Project Access from the Access Manager menu in the navigation bar.
- Next to the Projects menu, expand the Options menu, click Project Settings, and click Access Manager in the sidebar.
The Project Access Manager page displays.

Click the Applications tab.

Click Service Accounts.

Remove the service account.

Click the icon under Actions to the right of the service account you want to remove from the project.
Click Remove from this project.

Important

The service account still exists in the organization and any existing credentials remain active until expired or manually revoked.

Make an API Request

The Cloud Manager API uses one of two authentication methods to authenticate requests: API keys or a service account. You'll need the keys or the secret that you saved when configuring your preferred authentication method to complete the following procedures.

Your request should resemble the following examples, where {PUBLIC-KEY} is your API public key and {PRIVATE-KEY} is the corresponding private key.

The following sample GET request returns all projects for the current user:

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --header "Accept: application/json" \
     --include \
     --request GET "https://cloud.mongodb.com/api/public/v1.0/groups?pretty=true"

The following sample POST request takes a request body and creates a project named MyProject in your organization:

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --header "Accept: application/json" \
     --header "Content-Type: application/json" \
     --include \
     --request POST "https://cloud.mongodb.com/api/public/v1.0/groups?pretty=true" \
     --data '
       {
         "name": "MyProject",
         "orgId": "deffb2031b938da53f16d714"
       }'

To make an API request using a service account, use the service account to generate an access token, then use the access token in your request:

Retrieve the client secret for your service account.

Locate the client secret beginning with mdb_sa_sk_ that you saved immediately after creating the service account, which was the only time you could view the client secret. If you did not save the client secret, you must generate a new client secret.

Base64-encode the client ID and secret.

For example, run:

echo -n {CLIENT-ID}:{CLIENT-SECRET} | base64

Request an access token.

Replace {BASE64-AUTH} in the following example with the output from the preceding step, then run:

1 curl --request POST \
2      --url https://cloud.mongodb.com/api/oauth/token \
3      --header 'accept: application/json' \
4      --header 'cache-control: no-cache' \
5      --header 'authorization: Basic {BASE64-AUTH}' \
6      --header 'content-type: application/x-www-form-urlencoded' \
7      --data 'grant_type=client_credentials'

{"access_token":"eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6ImYyZjE2YmE4LTkwYjUtNDRlZS1iMWYLTRkNWE2OTllYzVhNyJ9eyJpc3MiOiJodHRwczovL2Nsb3VkLWRldi5tb25nb2RiLmNvbSIsImF1ZCI6ImFwaTovL2FkbWluIiwic3ViIjoibWRi3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImNpZCI6Im1kYl9zYV9pZF82NjI4MWJjNjAzYTcxYTQzMGI5MZlZjciLCJhY3RvcklkIjoibWRiX3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImlhdCI6MTcxMzkwNTM1OSiZXhwIjoxNzEzOTA4OTU5LCJqdGkiOiI4ZTg1MTM3YS0wZGU1LTQ0N2YtYTA0OS1hMmVmNTIwZGJhNTIifQAZSFvhcjwVcJYmvW6E_K5UnDmeiX2sJgL27vo5ElzeBuPawRciKkn6ervZ6IpUTx2HHllGgAAMmhaP9B66NywhfjAXC67X9KcOzm81DTtvDjLrFeRSc_3vFmeGvfUKKXljEdWBnbmwCwtBlO5SJuBxb1V5swAl-Sbq9Ymo4NbyepSnF""expires_in":3600,"token_type":"Bearer"}%

Important

The access token is valid for 1 hour (3600 seconds). You can't refresh an access token. When this access token expires, repeat this step to generate a new one.

Make an API call.

Replace {ACCESS-TOKEN} in the following example with the output from the preceding step. For example, --header 'Authorization: Bearer eyJ...pSnF' \.

The following sample GET request returns all projects for the current user:

curl --request GET \
      --url https://cloud.mongodb.com/api/public/v1.0/groups \
      --header 'Authorization: Bearer {ACCESS-TOKEN}' \
      --header 'Accept: application/json' \

The following sample POST request takes a request body and creates a project named MyProject in your organization:

curl --header 'Authorization: Bearer {ACCESS-TOKEN}' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --include \
     --request POST 'https://cloud.mongodb.com/api/public/v1.0/groups' \
     --data '
       {
         "name": "MyProject",
         "orgId": "5a0a1e7e0f2912c554080adc"
       }'

Back

Configure API Access

Cloud Manager Administration API Tutorials

1	curl --request POST \
2	--url https://cloud.mongodb.com/api/oauth/token \
3	--header 'accept: application/json' \
4	--header 'cache-control: no-cache' \
5	--header 'authorization: Basic {BASE64-AUTH}' \
6	--header 'content-type: application/x-www-form-urlencoded' \
7	--data 'grant_type=client_credentials'

Manage Programmatic Access to an Organization

Note

Required Permissions

Grant Programmatic Access to an Organization

In MongoDB Cloud Manager, go to the .css-h15tq0{font-style:normal;font-weight:700;}Organization Settings page.

Go to the Organization Access Manager page.

Click Add new Application API Key.

Complete the API Key Information form.

Click Next.

Add Access List Values for this API Key.

Click Save.

Warning

Copy the Private Key Before Leaving this Page

In MongoDB Cloud Manager, go to the Organization Settings page.

Go to the Organization Access Manager page.

Click Add new Application Service Account.

Enter the service account information.

Click Create.

Copy and save the Client Secret.

Warning

Add an API Access List Entry.

View Programmatic Access to an Organization

In MongoDB Cloud Manager, go to the Organization Settings page.

Go to the Organization Access Manager page.

Click the Applications tab.

Click API Keys.

Navigate to View Details.

In MongoDB Cloud Manager, go to the Organization Settings page.

Go to the Organization Access Manager page.

Click the Applications tab.

Click Service Accounts.

Update Programmatic Access to an Organization

In MongoDB Cloud Manager, go to the Organization Settings page.

Go to the Organization Access Manager page.

Click the Applications tab.

Click API Keys.

Select the API Key to edit.

Complete the API Key Information form.

Click Next.

Add Access List Values for this API Key.

Click Save.

Warning

Copy the Private Key Before Leaving this Page

In MongoDB Cloud Manager, go to the Organization Settings page.

Go to the Organization Access Manager page.

Click the Applications tab.

Click Service Accounts.

Click the name of a service account.

Edit the Service Account Info.

Generate a new client secret.

Edit the Organization Permissions.

Important

Edit the API Access List.

Revoke Programmatic Access to an Organization

In MongoDB Cloud Manager, go to the Organization Settings page.

Go to the Organization Access Manager page.

Click the Applications tab.

Click API Keys.

Delete the API Key.

Note

In MongoDB Cloud Manager, go to the Organization Settings page.

Go to the Organization Access Manager page.

Click the Applications tab.

Click Service Accounts.

Delete the service account.

Manage Programmatic Access to a Project

Note

Required Permissions

Grant Programmatic Access to a Project

In MongoDB Cloud Manager, go to the Project Access Manager page.

Click Create Application API Key.

Complete the API Key Information form.

Click Next.

Add Access List Values for this API Key.

Click Save.

Warning

Copy the Private Key Before Leaving this Page

In MongoDB Cloud Manager, go to the Project Access Manager page.

Click Create Application Service Account.

Enter the service account information.

In MongoDB Cloud Manager, go to the Organization Settings page.