- API >
- API Resources >
- User API Whitelist
User API Whitelist¶
On this page
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. |
Links¶
| Relation | Description |
|---|---|
self |
Me |
http://mms.mongodb.com/user |
The user that owns this whitelist. |
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" : [ ... ]
}