Navigation

User API Whitelist

The /users/USER-ID/whitelist resource retrieves and updates your API whitelist. If you have the Owner role, you can perform whitelisted API operations from the IP addresses you have added to this list.

The resource’s POST and DELETE operations are themselves whitelisted. They must originate from an address already on your API whitelist.

You can access the API whitelist only for the current user. The username and API key you use to authenticate must be those of the user identified in the endpoint. The endpoint identifies the user by user ID. To retrieve user IDs, see Get All Users in a Group.

Note

The /users/USER-ID/whitelist resource should not be confused with the /groups/GROUP-ID/whitelist resource, which controls client access to the group’s MongoDB clusters.

Endpoints

Get the API Whitelist for the Current User

GET /api/atlas/v1.0/users/USER-ID/whitelist

Get the API Whitelist Entry for a Specified Address or CIDR Block

The following retrieves the whitelist entry that contains an ipAddress value that matches IP-ADDRESS.

GET /api/atlas/v1.0/users/USER-ID/whitelist/IP-ADDRESS

The following retrieves the whitelist entry that contains a cidrBlock value that matches CIDR-BLOCK. Replace the forward slash (/) in the CIDR-notated address range with %2F. For example, specify 1.2.3.4%2F16 for 1.2.3.4/16.

GET /api/atlas/v1.0/users/USER-ID/whitelist/CIDR-BLOCK

Add Entries to the User’s API Whitelist

POST /api/atlas/v1.0/users/USER-ID/whitelist

The entity body must be an array of objects, even if it contains only one object. Each object should specify either the cidrBlock field or ipAddress field, but not both.

If an address is already in the whitelist, it will be ignored.

If you specify a single IP address with the /32 subnet mask, Atlas does not store the /32, as the /32 does not change the address. For example, an address of 12.34.56.78 is the same as 12.34.56.78/32.

Delete an Entry from the User’s API Whitelist

DELETE /api/atlas/v1.0/users/USER-ID/whitelist/IP-ADDRESS
DELETE /api/atlas/v1.0/users/USER-ID/whitelist/CIDR-BLOCK

You cannot remove your current IP address from the whitelist.

Sample Entity

{
  "cidrBlock" : "1.2.3.4/16",
  "created": "2016-08-02T12:34:56Z",
  "ipAddress": "1.2.3.4",
  "lastUsed" : "2016-08-23T15:42:50Z",
  "lastUsedAddress" : "1.2.3.4",
  "count": 19
}

Entity Fields

Name Type Description
cidrBlock string A CIDR-notated range of IP addresses. Entering 0.0.0.0/0 gives unrestricted access to whitelisted operations.
created date The date this IP address was added to the whitelist.
ipAddress string A whitelisted IP address.
lastUsed date The date of the most recent request that originated from this IP address. Note that this field is only updated when a resource that is protected by the whitelist is accessed.
lastUsedAddress string The last call to the API was issued from this address.
count integer The total number of requests that originated from this IP address. Note that this field is only updated when a resource that is protected by the whitelist is accessed.

Examples

Get the API Whitelist for the Current User

Request

curl -i -u "username:apiKey" --digest "https://cloud.mongodb.com/api/atlas/v1.0/users/5356823b3004dee37132bb7b/whitelist"

Response

HTTP/1.1 200 OK

{
  "results" : [ {
    "cidrBlock" : "6.7.8.9/30",
    "count" : 2,
    "created" : "2016-08-02T16:17:44Z",
    "lastUsed" : "2016-08-19T14:15:52Z",
    "lastUsedAddress" : "6.7.8.7",
    "links" : [ ... ]
  }, {
    "cidrBlock" : "1.2.3.4/32",
    "count" : 9,
    "created" : "2016-08-02T14:46:14Z",
    "ipAddress" : "1.2.3.4",
    "lastUsed" : "2016-08-24T15:42:23Z",
    "lastUsedAddress" : "1.2.3.4",
    "links" : [ ... ]
  } ],
  "totalCount" : 2,
  "links" : [ ... ]
}

Get the API Whitelist Entry for a Specified Address or CIDR Block

Request

curl -i -u "username:apiKey" --digest "https://cloud.mongodb.com/api/atlas/v1.0/users/5356823b3004dee37132bb7b/whitelist/12.34.56.78"

Response

HTTP/1.1 200 OK

{
  "cidrBlock" : "12.34.56.78/32",
  "ipAddress" : "12.34.56.78",
  "created" : "2016-08-18T16:17:44Z",
  "count" : 4,
  "links" : [ ... ]
}

Add Entries to the User’s API Whitelist

Request

curl -i -u "username:apiKey" -H "Content-Type: application/json" --digest -X POST "https://cloud.mongodb.com/api/atlas/v1.0/users/5356823b3004dee37132bb7b/whitelist" --data '
[ {
    "ipAddress" : "76.54.32.10"
  }, {
    "ipAddress" : "2.3.4.5"
} ]'

Response

HTTP/1.1 201 Created

{
  "results" : [ {
    "cidrBlock" : "12.34.56.78/32",
    "ipAddress" : "12.34.56.78",
    "created" : "2016-08-18T16:17:44Z",
    "lastUsed" : "2016-08-23T19:34:05Z",
    "lastUsedAddress" : "12.34.56.78",
    "count" : 5,
    "links" : [ ... ]
  }, {
    "cidrBlock" : "76.54.32.10/32",
    "ipAddress" : "76.54.32.10",
    "created" : "2016-08-17T19:34:05Z",
    "count" : 0,
    "links" : [ ... ]
  }, {
    "cidrBlock" : "2.3.4.5/32",
    "ipAddress" : "2.3.4.5",
    "created" : "2016-08-17T19:34:05Z",
    "count" : 0,
    "links" : [ ... ]
  } ],
  "totalCount" : 3,
  "links" : [ ... ]
}

Delete an Entry from the User’s API Whitelist

Request

curl -i -u "username:apiKey" --digest -X DELETE "https://cloud.mongodb.com/api/atlas/v1.0/users/5356823b3004dee37132bb7b/whitelist/2.3.4.5"

Response

HTTP/1.1 200 OK