DJ Walker

Stanimira Vlaeva

Developer Advocate



<div class="introduction">

The real power of a cloud-hosted, fully managed service like [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) is that you can create whole new database deployment architectures automatically, using the services API. Getting to the [MongoDB Atlas Administration API](https://docs.atlas.mongodb.com/api/) is relatively simple and, once unlocked, it opens up a massive opportunity to integrate and automate the management of database deployments from creation to deletion. The API itself is an extensive REST API. There's role-based access control and you can have [user or app-specific credentials](https://docs.atlas.mongodb.com/configure-api-access/) to access it.

There is one tiny thing that can trip people up though. The credentials have to be passed over using the [digest authentication mechanism](https://en.wikipedia.org/wiki/Digest_access_authentication), not the more common basic authentication or using an issued token. Digest authentication, at its simplest, waits to get an HTTP `401 Unauthorized` response from the web endpoint. That response comes with data and the client then sends an encrypted form of the username and password as a digest and the server works with that.

And that's why we’re here today: to show you how to do that with the least fuss in Python, Node, and Ruby. In each example, we'll try and access the base URL of the Atlas Administration API which returns a JSON document about the underlying applications name, build and other facts.
You can find all code samples in the dedicated [Github repository](https://github.com/mongodb-developer/atlas-admin-api-digest-auth).

## Setup

To use the Atlas Administration API, you need… a MongoDB Atlas account! If you don’t have one already, follow the [Get Started with Atlas](https://www.mongodb.com/docs/atlas/getting-started/) guide to create your account and first cluster.

The next requirement is the organization API key. You can set it up in two steps:

[Create an API key](https://www.mongodb.com/docs/atlas/configure-api-access/#std-label-create-org-api-key) in your Atlas organization. Make sure the key has the Organization Owner permission.
Add your IP address to the [API Access List for the API key](https://www.mongodb.com/docs/atlas/configure-api-access/#add-an-api-access-list-entry).

Then, open a new terminal and export the following environment variables, where `ATLAS_USER` is your public key and `ATLAS_USER_KEY` is your private key.

```
export ATLAS_USER=<public_key>
export ATLAS_USER_KEY=<private_key>
```

You’re all set up! Let’s see how we can use the Admin API with Python, Node, and Ruby.

</div>

<div class="content">

## Python

We start with the simplest and most self-contained example: Python.

In the Python version, we lean on the `requests` library for most of the heavy lifting. We can install it with `pip`:

``` bash
python -m pip install requests
```

The implementation of the digest authentication itself is the following:

``` python
import os
import requests
from requests.auth import HTTPDigestAuth
import pprint

base_url = "https://cloud.mongodb.com/api/atlas/v2/"
auth = HTTPDigestAuth(
   os.environ["ATLAS_USER"],
   os.environ["ATLAS_USER_KEY"]
)

headers = {
    'Accept': 'application/vnd.atlas.2023-01-01+json'  # update date to desired API version
}

response = requests.get(base_url, auth = auth, headers=headers)
pprint.pprint(response.json())
```

As well as importing `requests`, we also bring in `HTTPDigestAuth` from requests' `auth` module to handle digest authentication. The `os` import is just there so we can get the environment variables `ATLAS_USER` and `ATLAS_USER_KEY` as credentials.  We also add a header to set the [version of the Atlas Administration API](https://www.mongodb.com/docs/atlas/api/versioned-api-overview/#std-label-api-versioning-overview) that we want.  The `pprint` import is just to format our results.

The critical part is the addition of `auth = HTTPDigestAuth(...)` to the `requests.get()` call. This installs the code needed to respond to the server when it asks for the digest.

If we now run this program...

![Screenshot of the terminal emulator after the execution of the request script for Python. The printed message shows that the request was successful.][1]

…we have our API response.


## Node.js

For Node.js, we’ll take advantage of the `urllib` package which supports digest authentication.

``` bash
npm install urllib
```

The code for the Node.js HTTP request is the following:

``` javascript
const urllib = require('urllib');
const util = require('util');

const baseUrl = 'https://cloud.mongodb.com/api/atlas/v2/';
const { ATLAS_USER, ATLAS_USER_KEY } = process.env;
const options = {
  digestAuth: `${ATLAS_USER}:${ATLAS_USER_KEY}`,
  headers: {
    'Accept': 'application/vnd.atlas.2023-01-01+json'  // update date to desired API version
  }
};

urllib.request(baseUrl, options)
  .then(({ data, res }) => {
    if (res.statusCode !== 200) {
      console.error(`Unexpected Status: ${res.statusCode}: ${res.statusText}`);
    } else {
      const jsonRes = JSON.parse(data);
      console.log(util.inspect(jsonRes, { depth: null, colors: true }));
    }
  })
  .catch(error => console.error('Error occurred:', error));

```

Taking it from the top… we first require and import the `urllib` package. Then, we extract the `ATLAS_USER` and `ATLAS_USER_KEY` variables from the process environment and use them to construct the authentication key. Then we add a header to set the [version of the Atlas Administration API](https://www.mongodb.com/docs/atlas/api/versioned-api-overview/#std-label-api-versioning-overview) that we want. Finally, we send the request and handle the response in the passed callback. 

And we’re ready to run:

![Screenshot of the terminal emulator after the execution of the request script for Node.js. The printed message shows that the request was successful.][1]

On to our final language...

## Ruby

HTTParty is a widely used Gem which is used by the Ruby and Rails community to perform HTTP operations. It also, luckily, supports digest authentication. So, to get the party started:

``` bash
gem install httparty
```

There are two ways to use HTTParty. One is creating an object which abstracts the calls away while the other is just directly calling methods on HTTParty itself. For brevity, we'll do the latter. Here's the code:

``` ruby
require 'httparty'
require 'json'

base_url = 'https://cloud.mongodb.com/api/atlas/v2/'
options = {
  :digest_auth => {
    :username=>ENV['ATLAS_USER'],
    :password=>ENV['ATLAS_USER_KEY']
  },
  headers: {
    'Accept' => 'application/vnd.atlas.2023-01-01+json' # update date to desired API version
  }
}

}

result = HTTParty.get(base_url, options)

pp JSON.parse(result.body())
```

We require the HTTParty and JSON gems first. We then create a dictionary with our username and key, mapped for HTTParty's authentication, and set a variable to hold the base URL. Finally we add a header to set the [version of the Atlas Administration API](https://www.mongodb.com/docs/atlas/api/versioned-api-overview/#std-label-api-versioning-overview) that we want. We're ready to do our GET request now, and in the `options` (the second parameter of the GET request), we pass `:digest_auth=>auth` to switch on the digest support. We wrap up by JSON parsing the resulting body and pretty printing that. Put it all together and run it and we get:

![Screenshot of the terminal emulator after the execution of the request script for Ruby. The printed message shows that the request was successful][1]

</div>

<div class="summary">

## Next Stop - The API

In this article, we learned how to call the [MongoDB Atlas Administration API](https://docs.atlas.mongodb.com/api/) using digest authentication. We took advantage of the vast library ecosystems of Python, Node.js, and Ruby, and used the following open-source community libraries:

Requests for Python
urllib for JavaScript
httparty for Ruby

If your project requires it, you can implement digest authentication yourself by following the [official specification](https://datatracker.ietf.org/doc/html/rfc7616). You can draw inspiration from the implementations in the aforementioned libraries.

Additionally, you can find all code samples from the article in Github.

With the authentication taken care of, just remember to be fastidious with your API key security and make sure you revoke unused keys. You can now move on to explore the API itself. Start in the [documentation](https://docs.atlas.mongodb.com/api/) and see what you can automate today.


</div>


  [1]: https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt58ba511eb158a659/6672112e46a0375ae0a29f57/Ruby-Response_NO_IP.jpg

Learn how to use digest authentication for the MongoDB Atlas Administration API from Python, Node.js, and Ruby.

DJ Walker

Content by DJ Walker

Calling the MongoDB Atlas Administration API: How to Do it from Node, Python, and Ruby