FAQs

• What are APIs
• How can I test and play with APIs
• How do I build an API request
• 401 Errors
• 403 Errors
• 400 Errors
• 404 Errors
• 429 Errors
• 500 Errors
• Licensing and Usage APIs
• Curl Scripting APIs
• Legacy APIs
• Submitting Feedback

 

Q: What are APIs?

API = Application Programming Interface

• APIs are user interfaces for programmers and integrators to automate tasks or extend capabilities of an application or platform beyond it’s originally defined capabilities.
• APIs consist of several parts generally all required to execute a successful request
  • Verb
    • Predefined actions to allow for (CRUD) operations
      • Create = POST
      • Read = GET
      • Update = POST/PATCH
      • Delete = Delete
  • URL
    • Generally utilitarian in nature allowing you to determine the intent of the API by sight without the need for extensive documentation
      • Example: GET /dogs – retrieves a list of all dogs
    • Query string parameters - allows the ability to perform additional functions within the URL without having to build complicated JSON body requests
      • Example: Filter response to return only brown dog
        • GET /dogs?color=brown
  • Header
    • Key/Value pairs to define authentication mechanism, type of content, or in Sophos Central APIs, define the partner or sub organization to execute the API requests against
    • Authentication : Bearer + <AUTH TOKEN>
    • Content-Type : application/JSON*
    • X-Partner-ID : <Partner GUID>
  • Body
    • Request – Ability to input specific data to be persisted in the program
    • Example: POST /dogs
    • {”Type:”:”Retriever”, “Color”:”Golden”, ”Name”:”Biscuit”, “Age”: “7 years”}
  • Response – Data returned from the request
    • {“Id”:ABC123, ”Type:”:”Retriever”, “Color”:”Golden”, ”Name”:”Biscuit”, “Age”: “7 years”}

*Note: *Sophos Central useses Java Script Object Notation (JSON) as a content type for all of our public facing APIS

Q: How can I test and play with APIs?

• The internet is full of documentation and tools available to design against, develop, and test API integrations. Here are a few of the useful tools we recommend:
  • API Design Principles Tutorial
  • Postman – A robust API building and troubleshooting tool. The preferred tool of Sophos Central Engineering
    • Sophos provides prebuilt ready to import collections for our APIs.
  • Powershell Developer Documentation
  • Python Developer Documentation
  • Stack Exchange – A widely known community used by developers for troubleshooting issues across a variety of scripting and developer languages.

 

Q: How do I build an API request

• Please see Building an API request in our Getting Started with Sophos APIs Guide

 

Q: I’m getting a 401 "Unauthorized" error

• Please see here for Authorization troubleshooting steps

 

Q: I’m getting a 403 “Forbidden” error

• Please see here for Permissions troubleshooting steps

 

Q: I’m getting a 400 “Bad Request” error

• Please see here for JSON formatting troubleshooting steps

 

Q: I’m getting a 404 “Not Found” error

• Please see here for 404 troubleshooting steps

 

Q: I’m getting a 429 “Too many requests” error

• Please see here for Throttling troubleshooting steps

 

Q: I’m getting a 500 “Unexpected” error

• Please see here for System error troubleshooting steps

 

Q: I’m looking for licensing and usage APIs?

• We don’t currently offer Licensing and Usage APIs. However, we are currently looking to get them on our Roadmap for the 2021 calendar year.

As a possible solution to your business needs, we do offer two integrations with primary vendors in the Professional Services and Automation space where this data can be synced directly from Sophos Central Partner Admin.
See Autotask and ConnectWise PSA integration documentation for more details.

 

Q: cURL Script errors

I copied your cURL script for authentication directly from your Getting Started Guide in the developer.sophos.com portal but am receiving the following errors:

• ‘client_id’ is not recognized as in internal or external command
• Could not resolve host: <XXXX>

Our script contains back slashes “/” to make the command easier to read. These extraneous characters as well as, all returns and line breaks must be removed in order for the script to execute successfully.

Q: I am getting an InvalidArgument: (:) [Invoke-WebRequest], ParameterBindingException error in Powershell when using your cURL script for authentication.

The cURL sample provided in our Developer portal was a general example written for a standard curl.exe application and the syntax may differ depending on how and where it is executed. Specifically, different versions of Powershell handle cURL differently. In terms of the specific error referenced above, it looks as though cURL is just an alias for the Invoke-WebRequest Powershell command. According to Powershell documentation, it doesn’t like a string being passed for the Headers value, but rather requests an iDictionary or hash value to be defined in it’s place.

Below is a command written specifically for Powershell:
Invoke-WebRequest -Method POST -Uri id.sophos.com/.../token -ContentType "application/x-www-form-urlencoded" -Body"grant_type=client_credentials&client_id=XXXXXXXX6&client_secret=XXXXXXXX&scope=token"

  

Q: What is the difference between your older SIEM API and these new APIs?

The original SIEM API was a large unstructured data dump of only Alerts and Events (community.sophos.com/.../125398)

• Didn’t allow authentication and management at the partner level but at each individual tenant level
• Didn’t conform to standards for authentication or data structures

The New Sophos Central APIs (https://developer.sophos.com/)

• Allow for a streamlined coherent user experience across all current and future public APIs.
• Allows authentication and management at the partner level backed by industry standard authentication mechanisms and tokens
• Supports multiple API’s for Partner and Enterprise Dashboard (and soon to include Central Dashboard in early 2020)
• Does not yet provide access to Events

 

Q: Can I still use the original SIEM API?

Yes, at current the original Alert and Event APIs are still available. At some point in the future we will publish a new API following our current standards and this API will become deprecated.

• We will not shut off access without publishing a migration plan and allowing sufficient time for our customers to onboard with the new API.

 

Q: Where can I submit feature requests or feedback about the APIs?

• You can email us at: apis@sophos.com
• Post in the Feedback section of this forum

Added link for postman collections in public GitHub repository.
[edited by: Elias Collins - Sophos Product Management at 3:54 PM (GMT -7) on 26 Mar 2021]