- API >
- API Resources >
- Group IP Whitelist
Group IP Whitelist¶
On this page
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. |
Links¶
| Relation | Description |
|---|---|
self |
Me |
http://mms.mongodb.com/group |
The group containing 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
}