Fix This Page
Navigation
You were redirected from a different version of the documentation. Click here to go back.

Whitelist

The whitelist resource lets you retrieve and update a user’s whitelist, which controls the user’s access to whitelisted API operations. Users can issue whitelisted API operations only from addresses on their own whitelists.

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

To use the whitelist resource you must know the ID of the user who owns the whitelist. To retrieve a user’s ID, see Get All Users in a Group.

You can access whitelist information only for the user issuing the request. The USER-ID in the URL must match the ID of the user associated with the Public API key used to send the request.

Endpoints

Get the API Whitelist for the Current User

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

Get the Whitelist Entity for a Specific IP Address

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

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

This retrieves a whitelist entity if the value of IP-ADDRESS equals the value of the entity’s ipAddress field. This does not retrieve an object where the value of IP-ADDRESS is contained within the values allowed by the cidrBlock field.

Add Entries to the API Whitelist for the Current User

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

The entity body must be an array of whitelist entities, even if there is only one. The only field you need to specify for each entity is the ipAddress.

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

If you specify a single IP address with the /32 subnet mask, Ops Manager 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 API Whitelist for the Current User

DELETE /api/public/v1.0/users/USER-ID/whitelist/IP-ADDRESS
DELETE /api/public/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/32",
  "created": "2014-01-02T12:34:56Z",
  "ipAddress": "1.2.3.4",
  "lastUsed" : "2016-04-25T15:42:50Z",
  "lastUsedAddress" : "1.2.3.4",
  "count": 1234
}

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 number 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://<ops-manager-host>/api/public/v1.0/users/5356823b3004dee37132bb7b/whitelist"

Response

HTTP/1.1 200 OK

{
  "results" : [ {
    "cidrBlock" : "5.6.7.8/30",
    "count" : 482,
    "created" : "2014-04-23T16:17:44Z",
    "lastUsed" : "2016-04-19T14:15:52Z",
    "lastUsedAddress" : "5.6.7.7",
    "links" : [ ... ]
  }, {
    "cidrBlock" : "1.2.3.4/32",
    "count" : 9,
    "created" : "2016-02-19T14:46:14Z",
    "ipAddress" : "1.2.3.4",
    "lastUsed" : "2016-04-25T15:42:50Z",
    "lastUsedAddress" : "1.2.3.4",
    "links" : [ ... ]
  } ],
  "totalCount" : 2,
  "links" : [ ... ]
}

Get the Whitelist Entity for a Specific IP Address

Request

curl -i -u "username:apiKey" --digest "https://<ops-manager-host>/api/public/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" : "2014-04-23T16:17:44Z",
  "count" : 482,
  "links" : [ ... ]
}

Add Entries to the API Whitelist for the Current User

Request

curl -i -u "username:apiKey" -H "Content-Type: application/json" --digest -X POST "https://<ops-manager-host>/api/public/v1.0/users/5356823b3004dee37132bb7b/whitelist" --data '
[ {
    "ipAddress" : "76.54.32.10"
  }, {
    "ipAddress" : "2.3.4.5"
} ]'

Response

HTTP/1.1 201 Created

{
  "totalCount" : 3,
  "results" : [ {
    "cidrBlock" : "12.34.56.78/32",
    "ipAddress" : "12.34.56.78",
    "created" : "2014-04-23T16:17:44Z",
    "lastUsed" : "2016-08-17T19:34:05Z",
    "lastUsedAddress" : "12.34.56.78",
    "count" : 0,
    "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" : [ ... ]
  } ],
  "links" : [ ... ]
}

Delete an Entry from the API Whitelist for the Current User

Request

curl -i -u "username:apiKey" --digest -X DELETE "https://<ops-manager-host>/api/public/v1.0/users/5356823b3004dee37132bb7b/whitelist/2.3.4.5"

Response

HTTP/1.1 200 OK
←   Users Backup and Restore  →