Rest API Specification Guide

Root Endpoint

Authentication

OAuth2 is used as an authentication mechanism. Every Third-Party Vendor will get their unique Client Id and Client Secret to access the  OAuth2 id token. You can use the generated ID token for adding the Authorization header in each API call. Id token will expire after 30 minutes.

• Token endpoint:
  
  
• Sample request header:
  
  

Data Endpoints

• /v1/MSP
  

• /list

1. Type: GET
2. Sample Response:
   
   
   
   
   

• /{guid}/detail
  

1. Type: GET
2. Sample Response:
   
   

• /{guid}/org/list

1. Type: GET
2. Sample Response:
   
   

• {guid}/org/{orgDomain}/detail

1. Type: GET
2. Sample Response:
   
   
   
   

• /{guid}/org/{orgDomain}/user/list

1. Type: GET
2. Sample Response:
   
   

• /{guid}/org/{orgDomain}/alerts?interval=?&pageSize=?&pageNo=?

1. Type: GET
2. Sample Response:
   
   

• Sample Error Response
  
  

Data Definition

Query Parameters

1. interval:

• Value should contain a date range in 'Start date as milliseconds-End date as milliseconds' format. For example to get the alerts for date range 2021 Jul 1 01:00:00 to 2021 Jul 1 02:00:00 value of
  interval parameter should be 1625144400000-1625148000000.

2. pageSize:

• Format: A valid number. For example, to fetch 10 alerts set the value as 10.
• Validation: If the page size value exceeds 10 consumers will get an invalid page size error.

3. pageNo:

• Format: A valid number. For example, get 2 pages of alert data set the value as 2. Consumer needs to keep track of correct page no information.

Response fields

Fields that can only have a specified set of values are listed below. Value of all the other fields except these may vary with each API call.

1. categoryNames: Categories for which alert got generated in Graphus system. It will be a comma-separated list of below-listed values if it contains more than one value otherwise it will be a string containing any one of the below-listed values.

• Scam
• Phishing
• Spoofed Name
• Spoofed Sender
• Spoofed Domain
• Unauthorized Sender
• Undisclosed Recipients
• Malicious Attachment
• Drive-By Download Malware
• Malicious URL
• Executive Spoofing
• Spoofed Organization
• Sender Empty Subject and Body
• Trusted User Spoofing
• Organization Domain Display Spoofing
• Malicious Sender
• Suspicious Sender
• Not Yet Trusted Sender
• Compromised Internal Sender
• Organization Sender Impersonation

2. state: State of alert in Graphus system. Alert can be in any one of the below-listed states at a given point in time of its lifecycle.

• new
• open
• action
• trash
• ignored
• closed

3. severity: The severity of the alert is determined by the Graphus system. Alert can be in any one of the below-listed severities at the time of generation and alert severity does not change.

• low
• moderate
• high
• critical

4. indicatorOfThreat: You can find below a list of threat indicator values. It will be a comma-separated list if it contains more than one value from the below-listed values, otherwise, any one of the below-listed values is a string.

• Sender address doesn't match return and reply-to addresses
• The sender is not authorized to send emails from this server for your domain
• The server that sent this email is not authorized to send emails for that domain
• The sender's name closely resembles a trusted user in your organization
• Sender domain closely resembles your domain
• Email is sent as a bcc only and could be malicious
• The sender is not a legitimate user account in your organization
• The sender is either not known to your organization or has a suspicious interaction pattern
• The sender's name closely resembles a trusted user in your organization
• The sender's name closely resembles an executive user in your organization
• Malware and/or Malicious URL
• Spoofed organization sender
• An email has an empty subject and body
• Sender impersonated
• The sender display name shows your organizations domain but the email is sent from a different domain
• This sender has sent phishing attacks in the past
• This sender is not known to your organization. Please be careful before replying or clicking on any URL
• This sender is not yet trusted by your organization. Please be careful before replying or clicking on any URL
• The attributes of this email don't match the trusted profile of the sender
• This sender is trusted by your organization but the email has suspicious content. Please be careful before replying or clicking on any URL
• Organizational sender impersonation
• Sender found malicious after a user reported email analysis This sender has sent malicious links, attachments in the past This sender has sent phishing, scam attacks in the past

5. spf: Sender Policy Framework indicator values. This field will contain any one of the below-listed values:

• pass
• fail
• softfail
• neutral
• nne
• permerror
• temperror.

6. dkim: DomainKeys Identified Mail indicator values. This field will contain any one of the below-listed values.

• pass
• fail
• softfail
• neutral
• none
• permerror
• temperror.

7. code: This field will contain any one of the below-listed error codes.

• NO_DATA_FOUND
• INVALID_VALUE_INTERVAL
• INVALID_VALUE_PAGESIZE
• INVALID_VALUE_PAGENUMBER
• UNAUTHORIZED_ACCESS
• ACCESS_NOT_GRANTED.

Note: 

Response JSON will not include fields with a null value unless explicitly specified for any particular field.