API Documentation

Introduction

The API allows you to extract valuable information regarding your accounts, apps, status, scripts, incidents, lists, and reports. It serves as an alternative method to access this information and integrate it into your internal systems and other applications, beyond the Code Defender portal.

The API offers various endpoints, each providing distinct information and following specific structures outlined in accompanying documentation.

The API releases are versioned, and each version remains unchanged once released. Any necessary modifications or corrections to endpoints will result in a change of version, consequently leading to a change in the API address.

Accessing the API

To access the API, you must add an authentication token to the request. Read more about tokens here.
Requests without a token will return a 401 (Unauthorised) HTTP error.

1. To issue a token, in the HUMAN Console, go to Product Settings > Integrations Setting > API.
2. Copy the token.
3. Add the token in the request headers using this format:
   Authorization: Bearer <token>

Tokens

You can create multiple tokens, each of which enables access to sensitive information through the API.

Tokens are confidential and must be stored and handled accordingly. Each token is protected with a secret signature and has an expiration date. Make sure to generate a new token before the previous one expires. If you think a token has been compromised, contact HUMAN support.

API Address

The API address is structured as follows:
https://api-gw.perimeterx.com/<api-version>/<endpoint>

Endpoints

<GET> Incidents

http://api-gw.perimeterx.com/v1/incidents

Returns lists of incidents detected for the respective pair of the app ID and host domain.

Query Params

Response Example

{
    "paging": {
        "previous": "",
        "current": "https://10.192.0.80:80/v1/incidents?appId=ABC123&tld=example.com&take=20&skip=0",
        "next": "https://10.192.0.80:80/v1/incidents?appId=ABC123&tld=example.com&take=20&skip=20",
        "count": 1000
    },
    "data": [
        {
            "category": "pii",
            "script_ack": false,
            "incident": "Credentials - Email access is being made by a third party script",
            "details": "Accessing email address.",
            "initiator": "script.com/lib/main.[UNIQUE_ID].js",
            "first_seen": "2022-01-30T12:15:49Z",
            "last_seen": "2023-03-23T08:55:27Z",
            "host_domain": "example.com",
            "app_id": "ABC123",
            "page_types": [
                "checkout",
                "products_and_search"
            ],
            "page_types_per": {
                "checkout": 1.436782,
                "products_and_search": 0.015879
            },
            "ack": true,
            "ack_updated_at": "2022-04-26T08:54:22.084Z",
            "additional_data": {
                "vulnerabilities": null
            },
            "under_review": true,
            "risk_level": "high",
            "script": {
                "id": "sscript/lib/main.[UNIQUE_ID].js",
                "host_domain": "example.com",
                "type": "third_party",
                "vendor": "Pinterest",
                "users_affected_percentage": 31.001983,
                "first_seen": "2021-12-30T16:18:53Z",
                "last_seen": "2023-03-23T09:13:44Z",
                "risk": {
                    "level": "medium",
                    "reason": "PII sniffing"
                },
                "ack": false
            },
            "actions": null
        }
    ]
}

<GET> Scripts

http://api-gw.perimeterx.com/v1/scripts?appId=<app_id>&tld=<host_domain>&skip=0&take=20

Returns lists of actions allowed for the respective pair of the app ID and host domain.

Query Params

Response Example

{
    "paging": {
        "previous": "",
        "current": "https://api-gw.perimeterx.com/v1/scripts?accountName=Account&appId=ABC123&from=1674745735371&tld=domain.com&to=1674832135371&take=20&skip=0",
        "next": "https://api-gw.perimeterx.com/v1/scripts?accountName=Account&appId=ABC123&from=1674745735371&tld=domain.com&to=1674832135371&take=20&skip=20",
        "count": 1000
    },
    "data": [
        {
            "id": "pay.google.com/gp/p/js/pay.js",
            "host_domain": "example.com",
            "type": "third_party",
            "vendor": "Google",
            "users_affected_percentage": 4.06833,
            "first_seen": "2021-07-21T11:22:27+03:00",
            "last_seen": "2023-02-22T16:48:16+02:00",
            "risk": {
                "level": 100,
                "reason": "Baseline deviation on sensitive pages - iframe source"
            }
        },
        ...
    ]
}                

<GET> Allow Lists

http://api-gw.perimeterx.com/v1/allow-lists?<app_id>=<host_domain>&skip=0&take=20

Returns lists of allowed actions for respective pairs of app IDs and host domains.

Query Params

Response Example

{
    "paging": {
        "previous": "",
        "current": "https://api-gw.perimeterx.com/v1/allow-lists?ABC123=domain.com&take=20&skip=0",
        "next": "https://api-gw.perimeterx.com/v1/allow-lists?ABC123=domain.com&take=20&skip=20"
    },
    "data": [
        {
            "app_id": "ABC123",
            "host_domain": "domain.com",
            "count": 1000,
            "data": [
                {
                    "added_date": "2022-08-07T10:30:20.162+03:00",
                    "script": "connect.facebook.net/signals/config/123456789",
                    "vendor": "Facebook",
                    "category": "dom",
                    "action_type": "value_access",
                    "last_seen": "2021-07-30T16:38:24+03:00",
                    "action_args": {
                        "Element ID": "vemail",
                        "Element Name": "vemail"
                    }
                },
                ...
            ]
        },
        ...
    ]
}

<GET> Deny Lists

http://api-gw.perimeterx.com/v1/deny-lists?<app_id>=<host_domain>&skip=0&take=20

Returns lists of blocked actions for respective pairs of app IDs and host domains.

Query Params

Response Example

{
    "paging": {
        "previous": "",
        "current": "https://api-gw.perimeterx.com/v1/deny-lists?ABC123=domain.com&take=20&skip=0",
        "next": "https://api-gw.perimeterx.com/v1/deny-lists?ABC123=domain.com&take=20&skip=20"
    },
    "data": [
        {
            "app_id": "ABC123",
            "host_domain": "domain.com",
            "count": 16,
            "data": [
                {
                    "entity_value": "cdn.cdn.com/qscripts.js",
                    "type": "dom",
                    "subtype": "value_access",
                    "action_arg1": "dwfrm_creditCard_securityCode",
                    "action_arg2": "securityCode",
                    "last_seen": "2022-01-25T17:31:11+02:00",
                    "block_updated_at": "2022-06-13T08:59:44.448Z"
                },
                ...
            ]
        },
        ...
    ]
}

<GET> Cookie Report

http://api-gw.perimeterx.com/v1/cookie-report?<app_id>=<host_domain>&skip=0&take=20

Returns lists of data about cookies that were created for their respective pair of app ID and host domain.

Query Params

Response Example

{
    "paging": {
        "previous": "",
        "current": "https://api-gw.perimeterx.com/v1/cookie-report?ABC123=domain.com&from=1675209600000&take=20&skip=0",
        "next": "https://api-gw.perimeterx.com/v1/cookie-report?ABC123=domain.com&from=1675209600000&take=20&skip=20"
    },
    "data": [
        {
            "app_id": "ABC123",
            "host_domain": "domain.com",
            "count": 1000,
            "data": [
                {
                    "name": "weird_get_top_level_domain",
                    "vendor": "Cquotient (Salesforce)",
                    "description": "Cquotient (Salesforce)",
                    "first_seen": "2020-01-21T13:29:29+02:00",
                    "last_seen": "2023-02-27T16:12:21+02:00",
                    "scripts": [
                        "cdn.cquotient.com/js/v2/gretel.min.js"
                    ]
                },
                ...
            ]
        },
        ...
    ]
}

<GET> Account Settings

http://api-gw.perimeterx.com/v1/account-settings

Returns an object that contains general data about the account: applications, host domains, monthly unique visitors, types of configured alerts, last baseline creation date, whether Code Defender is enabled and whether client-side mitigation is enabled.

Query Params

<none>

Response Example

{
    "applications": [
        {
            "app_id": "ABC123",
            "enabled": true,
            "hostDomains": [
                {
                    "domain": "domain1.com",
                    "last_created_baseline": "2023-02-13T00:33:06+02:00"
                },
                {
                    "domain": "domain2.com",
                    "last_created_baseline": "2022-11-13T15:52:03+02:00"
                },
                ...
            ],
            "csm_enabled": true,
            "sensor_version": "2.1.1",
            "muvs": {
                "2022-08": 8698227,
                "2022-09": 9432064,
                "2022-10": 11399034,
                "2022-11": 15275195,
                "2022-12": 8480986,
                "2023-01": 10015053,
                "2023-02": 7668405
            }
        },
        ...
    ],
    "accountName": "Acount",
    "alerts": [
        {
            "name": "Tests 1",
            "type": "email",
            "notifications": [
                {
                    "app_id": "ABC123",
                    "host_domain": "domain1.com",
                    "notification_levels": {
                        "high": true,
                        "low": false,
                        "medium": false
                    }
                }
            ]
        },
        {
            "name": "Tests 2",
            "type": "slack",
            "notifications": [
                {
                    "app_id": "ABC123",
                    "host_domain": "domain1.com",
                    "notification_levels": {
                        "high": true,
                        "low": false,
                        "medium": true
                    }
                },
                {
                    "app_id": "ABC123",
                    "host_domain": "domain2.com",
                    "notification_levels": {
                        "high": true,
                        "low": false,
                        "medium": false
                    }
                }
            ]
        },
        ...
    ]
}

Code Examples

In order to get all incidents in the past month for all applications, do the following steps -

1. Request the account’s overall data:

https://api-gw.perimeterx.com/v1/account-settings

This will return an object with different account data. One of the fields, named applications, holds all the applications that were ever enabled on Code Defender. 

2. Using this array, you can extract all the app ids:

const appIds = accountSettingsresult.applications.map(application => application.app_id);

3. After obtaining all relevant app Ids, you can easily request all incidents using start and end timestamps from the past month:

const incidentsPerAppId = Promise.All(
  appIds.map(appId => fetch(`https://api-gw.perimeterx.com/v1/incidents?appId=${appId}&tld=example.com&from=1680307200000&to=1682899199000&take=20&skip=0`, 
    headers: {
      Authentication: 'Bearer <Token>'
    }
  ))
)

(This example shows timestamps for the full month of April 2023)

Error Handling