API Keys and Whitelisting

The API Science API provides users with the ability to directly access their API monitoring data using standard RESTful API conventions. Users can access information about their monitors, templates, API checks, contacts, and errors. The API can thus be used to create custom applications related to the APIs you monitor, tailored to the specific needs of your team.

In order to access the API, one or more API keys must be created for your account. To do this, click your account name in the upper right corner of your Dashboard page, and select “Settings”:

account-pull-down-menu

On the Settings page, click “API Keys”:

settings-api-keys

Click “Create New API Key” to generate an API key for your account:

create-new-api-key2

With the new API key in place, you can now access the API Science API. Most API operations can be performed using four standard HTTP methods: POST (create), GET (retrieve), PATCH (update), and DELETE (remove). The curl command line tool and library can also be used to access the API. In all cases, API requests must utilize SSL (that is, HTTPS).

For example, the API request to get all monitors for an account is:

GET https://api.apiscience.com/v1/monitors

This returns JSON that includes a “meta” section describing the result of the request and a “data” section consisting of an array of Monitor objects, formatted like this:

{
    "meta": {
        "status": "success",
        "numberOfResults": 2
    },
    "data": [
        {
            "id": 998832233,
            "name": "Monitor #1",
            "...": "..."
        },
        {
            "id": 19204332,
            "name": "Monitor #2",
            "...": "..."
        }
    ]
}

To retrieve your monitors information using curl, execute the following from a command prompt:

curl 'https://api.apiscience.com/v1/monitors' -H 'Authorization: Bearer YOUR_API_KEY'

(substituting your actual API key for YOUR_API_KEY). Notice that the API key is specified using the curl -H (header) option. This option sends the authorization information to the API endpoint as an HTTP header.

Using curl to retrieve the current list of monitors for the Acme API Monitors account produces the following result:

kevin@work ~/APIScience $ curl 'https://api.apiscience.com/v1/monitors' -H 'Authorization: Bearer MY_API_KEY'
{"meta":{"status":"success","numberOfResults":6},"data":[{"id":112,"href":"https://api.apiscience.com/v1/monitors/112.json","name":"Multi-step Example","frequency":1800,"active":true,"shared":true,"location":"Washington DC","tags":[],"summary":{"status":"up","performance":2142.05,"uptime":100.0,"lastCheckedAt":"2016-07-12T18:38:51.000Z"},"templates":[{"id":312,"href":"https://api.apiscience.com/v1/monitors/112/templates/312.json" ...

IP Whitelists

When you create an API Science API key, there is an option to specify an IP whitelist. This can be used to limit the validity of the API key to a specific IP address (wildcards are supported). For example, if you’ve created an application that uses the API Science API and you host the application on a public web site, it might be possible for an outsider to extract or intercept your API key. They might then use it to tamper with your API Science account.

But if you create an IP whitelist for the API key, then the key is valid only when the API is accessed from the specified IP address (you might specify that the key is valid only when your own web site accesses the API Science API, for example).

Here, I’ve specified that my API key is valid only when it is used from the www.yahoo.com domain:

api-key-ip-whitelist

I click the “Reissue” link to alter the API key to include the IP whitelist. Now, if I repeat my curl request for the Acme API Monitors data, I receive the following result:

kevin@work ~/APIScience $ curl 'https://api.apiscience.com/v1/monitors' -H 'Authorization: Bearer MY_API_KEY'
{"meta":{"status":"error"},"error":{"code":401,"name":"InvalidToken","message":"The API token MY_API_KEY is invalid.","infoUrl":"https://developer.apiscience.com/#error-reference"}}

Since I’m not calling the API Science API from Yahoo’s IP address, the API key is rejected.

–Kevin Farnham