Book IndexHideShow
Back to topic

Cloud Application Security

Cloud Application Security API Reference

Cloud Application Security API Reference

Imperva provides customers and partners with the ability to manage accounts and sites via an API.

Note: To better align with REST API standards and best practices, Imperva is gradually rolling out a new version of APIs, available for your use in managing your Cloud Application Security sites. For details, see API Version 2 Overview.

In this topic:

Overview

The API has the following characteristics:

  • Requests are HTTP POST.
  • Parameters are specified in the request body in HTML form style. For example:

    param1=value1&param2=value2
  • All requests are in SSL.
  • Response content is provided as a JSON document.
  • UTF-8 encoding is always used.

General request structure

Authentication

In order to use the API, the client must be authenticated by Imperva.

The preferred method is by submitting your API ID and API key using the x-API-Key and x-API-Id headers.

This is a more secure method than sending the API key and ID in the query string, preventing exposure of your personally identifiable information (PII).

Alternatively, you can authenticate by sending the api_id and api_key request parameters in the query string. For example:

api_id=12345&api_key=48d69342-eaec-44cf-8a5c-56c4ff1cd5e8

You can create and manage API keys with granular permissions and sub account access. For details, see API Key Management.

Account and site identifiers

Most API operations operate on a specific account or site. Use the following parameters to specify the account or site to operate on:

Name Description
account_id Numeric identifier of the account to operate on.
site_id Numeric identifier of the site to operate on.

Pagination

Some API operations may return a list of objects. Use the following parameters to enable paging:

Name Description Optional
page_size

The number of objects to return in the response.

Default: 50

Maximum: 100

Yes
page_num

The page to return starting from 0.

In order to view the full results, the client needs to run the API call with page_num set to 0, then again with page_num set to 1, and so forth.

Default: 0

Yes

Time range specification

Some operations require the user to specify a time range. This is done via the time_range parameter, which accepts the following values:

Name Description
today Retrieve data from midnight today until the current time.
last_7_days Retrieve data from midnight of 7 days ago until the current time.
last_30_days Retrieve data from midnight of 30 days ago until the current time.
last_90_days Retrieve data from midnight of 90 days ago until the current time.
month_to_date Retrieve data from midnight of the first day of the month until the current time.
custom

Specify a custom time range using two additional parameters: start and end.

Results are provided for full days only, starting from midnight. A time range of less than 24 hours gives results for the full day.

For example:

  • A time range of 14:00 - 20:00 yesterday gives results for all of yesterday (midnight to midnight) - a full day.
  • A time range of 14:00 last Tuesday to 14:00 last Wednesday gives results for all of Tuesday and Wednesday - two full days.
  • A time range of 14:00 yesterday to 14:00 today gives results for all of yesterday starting from midnight until the current time today.
Note:
  • If a time range is not specified, today is selected by default.
  • All dates should be specified as number of milliseconds since midnight 1970 (UNIX time * 1000). For details, see http://en.wikipedia.org/wiki/Unix_time.
  • Midnight is based on Coordinated Universal Time (UTC).
  • The available time ranges depend on the customer subscription plan.

General response structure

Every response contains the following fields in the returned JSON document:

Name Description
res The numeric result code for the operation. A result code of 0 indicates success.
res_message The textual representation of the result code (for example: "OK" - for success).
debug_info General information which is not strictly required for using the API, but is helpful to have.

For example:

{
    "res": 0,
    "res_message": "OK",
    "debug_info": {}
}
General error codes:
Code Description Comment
1 Unexpected error The server has encountered an unexpected error.
2 Invalid input Input missing or incorrect.
4 Operation timed-out or server unavailable The server is not available or reached a time-out while processing the operation.
9411 Authentication missing or invalid Authentication parameters missing or incorrect.
9403 Unknown/unauthorized account_id The specified account is unknown or client is not authorized to operate on it.
9413 Unknown/unauthorized site_id The specified site is unknown or client is not authorized to operate on it.
9414 Feature not permitted Feature is not available on account's plan.
9415 Operation not allowed The requested operation is not allowed.

Join the Discussion