API [Perception Point X‑Ray]

This page includes the following topics:

• API [Perception Point X‑Ray]
  • About the Perception Point X‑Ray API
  • API URL format
  • API Authentication
  • API throttling and retry
  • Flow chart diagram
  • API catalog

About the Perception Point X‑Ray API

The Perception Point X‑Ray API enables scanning of files and URLs to detect whether they are malicious or clean. You can also use the API to perform many other functions, such as changing the verdict of a scan, requesting a Perception Point IR Team investigation of a scan, or releasing an email from quarantine.

API URL format

In this Documentation Center, APIs are presented with the following format:

It is necessary to add the "https://<PERCEPTION-POINT-URL>" prefix to each of the APIs, where <PERCEPTION-POINT-URL> is:

This creates the full format of the required APIs, such as:

What is the environment of your organization In Perception Point X‑Ray, go to Account > Preferences. The Environment of your organization will appear under General > Info: US, EU, or AUS.

API Authentication

The request HEADERS for all API calls must contain an Authorization token:

• Header Key: "Authorization"

• Header Value: "Token <TOKEN_VALUE>"

Example

response = requests.post(
    "https://<PERCEPTION-POINT-URL>/someAPI/",
    headers={"Authorization": "Token <TOKEN_VALUE>"},
)

print response

{"scan_id": 123456}

Two types of authentication tokens are available:

• Organization-based: This is the recommended type of authentication token. API calls made using an organization-based token have permissions equivalent to admin users with the role "Administrator". For details on permissions for admin users, see About admin-user roles.

  • An API token for a parent organization will have access to the parent organization and to all child organizations.

  • An API token for a child organization will have access to that child organization only.

  Contact Perception Point Support [support@perception-point.io] and they will supply you with an authentication token for your organization - in a secure manner.

• User-based: Each Perception Point X‑Ray admin user has an associated API token. Using a user-based API token lets you control [reduce] the permissions of the resulting API calls - which have permissions equivalent to the associated admin users. A user-based token is less recommended than an organization-based token because a user-based token relies on the associated user constantly being a valid admin user in Perception Point X‑Ray.

  For details on how to get a user-based authentication token, see API Key.

  Tip: If you want to use user-based authentication, but you don't want to be dependent on a specific user constantly being part of the organization [and not leaving], then you can create a dedicated admin user for this purpose. For example, you could create an admin user with the user name "Dedicated API user." Creating a dedicated admin user also enables you to limit the permissions of the admin user by assigning the appropriate role. For API access, make sure to assign the new user the "Admin" role. If you require an API authentication token for the new dedicated admin user, you'll need to sign-in to Perception Point X‑Ray as the new dedicated user. For additional details, see API Key.

API throttling and retry

Throttling is based on the commercial agreement, with a default maximum of 100 API calls per minute. If you exceed this amount, you'll get error code 429, and you'll need to implement a retry mechanism in order to maintain the queue.

Flow chart diagram

API catalog

You can find information about the following APIs:

See also: 

• Incidents