Navigation

Personal API Key Whitelist

On this page

Note

Groups and projects are synonymous terms. Your {GROUP-ID} is the same as your project ID. For existing groups, your group/project ID remains the same. The resource and corresponding endpoints use the term groups.

Important

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

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 an Atlas User by Name.

Note

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

Endpoints

Get the API Whitelist for the Current User

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

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

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

Add Entries to the User’s API Whitelist

copy 
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

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

You cannot remove your current IP address from the whitelist.

Sample Entity

copy 
{
  "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.
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

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

Response

copy 
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

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

Response

copy 
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

copy 
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

copy 
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

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

Response

copy 
HTTP/1.1 200 OK

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.