Navigation

Group IP Whitelist

The /groups/GROUP-ID/whitelist resource retrieves and updates your group’s IP whitelist, which controls client access to your group’s MongoDB clusters. Clients can connect to clusters only from IP addresses on the whitelist.

Note

The /groups/GROUP-ID/whitelist should not be confused with the /users/USER-ID/whitelist resource, which controls access to a user’s API whitelist.

Endpoints

Get a Group’s IP Whitelist

GET /api/atlas/v1.0/groups/GROUP-ID/whitelist

Get the Entry for a Specific Address in a Group’s IP Whitelist

GET /api/atlas/v1.0/groups/GROUP-ID/whitelist/IP-ADDRESS-ENTRY

If the entry includes a subnet mask, use the URL-encoded value for the forward slash (/). For example, for an entry of 1.2.3.4/5, use 1.2.3.4%2F5.

Add Entries to a Group’s IP Whitelist

POST /api/atlas/v1.0/groups/GROUP-ID/whitelist

The entity body must be an array of entry objects, even if you are adding only one entry.

If an IP address is already in the whitelist, you will get an error.

When setting ipAddress, if you specify a single IP address and add the /32 subnet mask, Atlas does not store the /32 because a /32 subnet mask does not change the address. For example, an address of 12.34.56.78/32 is the same as 12.34.56.78.

To add or update the comment field for an existing whitelist entry, specify the either the ipAddress or the cidrBlock of the entry and the comment in the entity body passed to this endpoint. To remove the comment field for an existing whitelist entry, set comment to an empty string or exclude the comment from the entity body.

Delete an Entry from a Group’s IP Whitelist

DELETE /api/atlas/v1.0/groups/GROUP-ID/whitelist/IP-ADDRESS-ENTRY

If the entry includes a subnet mask, use the URL-encoded value for the forward slash (/). For example, for an entry of 1.2.3.4/5, use 1.2.3.4%2F5.

Sample Entity

{
  cidrBlock: "1.2.3.4/32",
  ipAddress: "1.2.3.4",
  groupId: "123abc",
  comment: "Comment on entry"
}

Entity Fields

Name Type Description
cidrBlock string The whitelist entry in CIDR notation.
ipAddress string The whitelisted IP address. This attribute will not be present if the whitelist entry is a CIDR block (e.g., 1.2.3.4/28).
groupId string ID of the group containing the whitelist entry.
comment string The comment to associate with the whitelist entry.

Examples

Get a Group’s IP Whitelist

Request

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

Response

HTTP/1.1 200 OK

{
  "links" : [ ... ],
  "results" : [
    {
      "cidrBlock" : "100.10.100.10/32",
      "groupId" : "5356823b3794dee37132bb7b",
      "ipAddress" : "100.10.100.10",
      "comment" : "Remote Office NA-West"
      "links" : [ ... ]
    },
    ...
  ],
  "totalCount" : 2
}

Get the Entry for a Specific Address in a Group’s IP Whitelist

Request

curl -i -u "username:apiKey" --digest "https://cloud.mongodb.com/api/atlas/v1.0/groups/5356823b3794dee37132bb7b/whitelist/100.10.100.10%2F32"

Response

HTTP/1.1 200 OK

{
  "cidrBlock" : "100.10.100.10/32",
  "groupId" : "5356823b3794dee37132bb7b",
  "ipAddress" : "100.10.100.10",
  "comment" : "Remote Office NA-West"
  "links" : [ ... ]
}

Add Entries to a Group’s IP Whitelist

Request

curl -i -u "username:apiKey" --digest -H "Content-Type: application/json" -X POST "https://cloud.mongodb.com/api/atlas/v1.0/groups/5759c4a4e4b0b1f3902bb6c9/whitelist" --data '
[
  {
    "ipAddress" : "76.54.32.10",
    "comment" : "Headquarter"

  }, {
    "cidrBlock": "72.53.34.15/28",
    "comment" : "Remote Office NA-East"
  }
]'

Response

HTTP/1.1 201 Created

{
  "links" : [ ... ],
  "results" : [
    {
       "cidrBlock" : "76.54.32.10/32",
       "groupId" : "5356823b3794dee37132bb7b",
       "ipAddress" : "76.54.32.10",
       "comment" : "Headquarters"
       "links" : [ ... ]
     },
     {
       "cidrBlock" : "72.53.34.15/28",
       "groupId" : "5356823b3794dee37132bb7b",
       "comment" : "Remote Office NA-East"
       "links" : [ ... ]
     },
     ...
  ],
  "totalCount" : 6
}

Delete an Entry from a Group’s IP Whitelist

Request

curl -i -u "username:apiKey" --digest -X DELETE "https://cloud.mongodb.com/api/atlas/v1.0/groups/5356823b3794dee37132bb7b/whitelist/72.53.34.15"

Response

HTTP/1.1 200 OK

{}
←   Root Database Users  →