Skip to main content
Skyhigh Security

Retrieve Evidence API

Save EvidenceSave Evidence is an advanced DLP feature that requires entitlement to a separate add-on SKU. Contact Skyhigh Support or your account manager for assistance.

Using the Retrieve Evidence API, you can download the saved evidence files or match highlight files that are associated with an incident. The files are retrieved from your configured Data Storage, decrypted, and returned. For details on saving the evidence files, see Save DLP Evidence.

NOTE: You can also download evidence files linked to DLP incidents individually from the Shadow/Web DLP Policy Incident Cloud Card on the Policy Incidents page. For details, see Download DLP Evidence.

 

API Location 

The API expects a GET request to retrieve_evidence endpoint. Depending on your tenant's location, use the following URLs: 

The API endpoint is as follows: 

GET /evidence/v1/evidence 

Authentication 

Authentication is required to use the API. The authentication shall be an IAM v2.0 token obtained from iam.skyhigh.cloud:

URL Example: https://iam.skyhigh.cloud/iam/v2/token.

The token obtained will then be supplied to the API as an HTTP header: Authorization: Bearer TOKEN.

Headers 

Some additional headers may be supplied to help.  

Header name 

Required 

Description 

X-RequestID 

No 

Optional header. The string supplied will be sanitized and used in the system logging to facilitate tracking throughout the system. 

Query Parameters 

Parameter Name 

Description 

tenant 

The ID of the tenant on behalf of whom the request is being made. This needs to match the tenant from the IAM token. 

ObjectID 

Identifier of the object within the cloud storage location.  The client must ensure the ID is correctly URL-encoded. This is obtainable from the incident. 

Responses 

Success 

On successfully obtaining the evidence file from the customer storage location and decrypting the data, the system shall respond with: 

200 OK 

The body of the response will be of type application/octet-stream and contain the decrypted data. 

Sample Request

GET /evidence/v1/retrieve_evidence?tenant=fbd752c4-f939-1037-9f75-
69bb489d9a5a&ObjectID=6%2Fe%2Ff%2Fs_3c31_3f46_36a06eff_8297_4137_a8d1_f83d8fbcd341-body.rtf.dlpenc 
Authorization:Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Im5ETVpoQkV0bmpZcnlPbU00M1ByYnJITmlKSSIsImtpZCI6Im5ETVpoQkV0bmpZcnl
PbU00M1ByYnJITmlKSSJ9.eyJuYmYiOjE2NzI4MzgzNTAsImV4cCI6MTY3MjgzODk2MCwiY2xpZW50X2lkIjoic1NiSDJXaGJnZHRSRW9CUW1QMXE5b1FRWiIsInN1YiI6InNT
YkgyV2hiZ2R0UkVvQlFtUDFxOW9RUVoiLCJpc3MiOiJodHRwczovL3ByZXByb2QuaWFtLm1jYWZlZS1jbG91ZC5jb20vaWFtL3YxLjAiLCJ0Z
W5hbnRfaWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJjbGllbnRfdHlwZSI6IkR4bFN0cmVhbWluZ1VzZXIiLCJhdWQiOiJtY2FmZWUiL
CJzY29wZSI6ImR4bHMuZXZ0LnciLCJ0b2tlbl9pZCI6ImRUbnNxd1pkdjNfWVp3MUdYaFBEVERPME0ifQ.27aEqZPZf5JCUmD3wH645ruzupqUE-RqlV0z7EPJemzws-
FANUlwhRZsqy9aTDSbymdkNhSBfH-Cz638bqusQzlPUfLW63HFc3xKLN2sVyCYrjBFxI8WzNZRKLjPGCqKmUB9lVs096HtzZZD3m4bmg7jDTminfds9LJNF9BFosmorAB11icidQCr
7rkSukBdWPzBC7DJXHIDERzi8dufS7vZLJZ2ybetMBSDQqzgk1VLZSMhc645frzvIitMgD28y7Cu1XfEz3Qa9yhBj13O7W95aDRgf6Uo6PuuU5gi-I-bDEPlpH7tbZFiNF7-6zpKcS
EDtHWtLoJYQIVjPe7SAA
X-RequestID:2006-08-14T02:34:56-06:00

Sample Response

200 OK 
Date:2006-08-14T02:34:56-06:00 
Connection:Close 
X-RequestID:2006-08-14T02:34:56-06:00 
Content-Type:application/octect-stream
 
Here is my decrypted evidence 

Error Schema 

Errors return a document of Content-Type: application/json containing additional information about the error.

{ 
    “error”:“string”, 
    “message”:“string” 
} 

Attribute Name 

Description 

error 

String enum representing the error.  All enum values TBD but may include BUCKET_REMOVED, BUCKET_PERMISSIONS, BAD_OR_MISSING_HEADER.

message 

Descriptive message about the error designed to be human-readable.

HTTP Error Codes 

Code 

Response 

Description 

400 

Bad Request 

For example, missing required parameter.

401  

Unauthorized 

Client authentication is missing or invalid. 

403 

Forbidden 

The client lacks sufficient authority to retrieve the requested resource. 

404  

Not Found 

The requested object was not found.

500 

Internal Server Error 

Something went wrong when processing the request. 

502  

Bad Gateway 

An upstream server e.g. AWS returned an unexpected response.

504  

Gateway Timeout 

An upstream server e.g. AWS S3 did not respond in a timely manner.

  • Was this article helpful?