Docs Menu
Docs Home
/
MongoDB Cloud Manager
/ /

Programmatic Access to Cloud Manager

On this page

  • Manage Programmatic Access to an Organization
  • Manage Programmatic Access to a Project
  • Make an API Request

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.

Note

Required Permissions

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.

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Click the Organization Settings icon next to the Organizations menu.

    The Organization Settings page displays.

2

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

3
4

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.

5
6

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.

7

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.

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Click the Organization Settings icon next to the Organizations menu.

    The Organization Settings page displays.

2

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

3
4
  1. Enter a Name.

  2. Enter a Description.

  3. Select a duration from the Client Secret Expiration menu.

  4. From the Organization Permissions menu, select the new role or roles for the service account.

5
6

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.

7
  1. Click Add Access List Entry.

  2. 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.

  3. Click Save.

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

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Click the Organization Settings icon next to the Organizations menu.

    The Organization Settings page displays.

2

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

3
4
5
  1. Next to the API Key, click .

  2. 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.

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Click the Organization Settings icon next to the Organizations menu.

    The Organization Settings page displays.

2

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

3
4

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

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.

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Click the Organization Settings icon next to the Organizations menu.

    The Organization Settings page displays.

2

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

3
4
5
  1. Click the next to the API Key you want to change.

  2. Click Edit.

6

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.

7
8

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.

9

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.

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Click the Organization Settings icon next to the Organizations menu.

    The Organization Settings page displays.

2

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

3
4
5
6

To modify the Name or Description, click .

7
  1. Click Generate New Client Secret

  2. Choose a duration for the client secret from the menu. The client secret expires after this duration.

  3. Click Generate New.

  4. Click Copy and save the client secret to a secure location. This is the only time you can view the full client secret.

8
  1. Click Edit Permissions.

  2. From the Organization Permissions menu, select the new role or roles for the service account.

  3. Click Save and next.

    Important

    The service account credentials remain active until they expire or a user revokes them.

9
  1. 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.

  2. To remove an IP address from the access list, click to the right of the IP address.

  3. Click Save.

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Click the Organization Settings icon next to the Organizations menu.

    The Organization Settings page displays.

2

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

3
4
5
  1. Click next to the API Key that you want to delete.

  2. 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.

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. Click the Organization Settings icon next to the Organizations menu.

    The Organization Settings page displays.

2

Click Access Manager in the sidebar.

The Organization Access Manager page displays.

3
4
5
  1. Click the icon under Actions to the right of the service account you want to delete.

  2. Click Delete.

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

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.

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.

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. 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.

2
3

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.

4
5

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.

6

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.

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. 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.

2
3
  1. Enter a Name.

  2. Enter a Description.

  3. Select a duration from the Client Secret Expiration menu.

  4. From the Project Permissions menu, select the new role or roles for the service account.

4
5

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.

6
  1. Click Add Access List Entry.

  2. 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.

  3. Click Save.

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

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. 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.

2
3
4
  1. Next to the API Key, click .

  2. 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.

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. 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.

2
3

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

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. 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.

2
3
4
  1. Click the next to the API Key you want to change.

  2. Click Edit.

5

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.

6
7

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.

8

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.

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. 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.

2
3
4
5

To modify the Name or Description, click .

6
  1. Click Generate New Client Secret

  2. Choose a duration for the client secret from the menu. The client secret expires after this duration.

  3. Click Generate New.

  4. Click Copy and save the client secret to a secure location. This is the only time you can view the full client secret.

7
  1. Click Edit Permissions.

  2. From the Project Permissions menu, select the new role or roles for the service account.

  3. Click Save and next.

    Important

    The service account credentials remain active until they expire or a user revokes them.

8
  1. 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.

  2. To remove an IP address from the access list, click to the right of the IP address.

  3. Click Save.

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. 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.

2
3
  1. Click next to the API Key that you want to delete.

  2. 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.

1
  1. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. 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.

2
3
4
  1. Click the icon under Actions to the right of the service account you want to remove from the project.

  2. 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.

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:

1

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.

2

For example, run:

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

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

1curl --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.

4

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 Access