This post will cover
- Creating a Service Principal
- Calling the Authentication API
- Using the Authentication token in subsequent API requests
1. Ensure that you have created your API Credentials as covered under the step 1 of the Getting Started Guide in the Sophos Developer Portal, detailed below for convenience
Create a service principal
- Sign in to Sophos Central Administrator dashboard as a Partner, Enterprise Admin, or Customer Admin.
- Click 'Settings & Policies' and then click the "API Credentials" link.
- Click 'Add Credential'
- Supply a name for your credential set and a description, then click 'Add'.
- Copy your Client ID and Secret for your records as the Secret will only be shown once.
2. Build an Authentication API request
- An Authentication API request contains the following components
- Verb
- URL
- Header
- Body
- An Authentication API response contains
- Authentication token (In this case a JSON WEB TOKEN)
- Authentication time to live - 3600 seconds
- Authentication type - Bearer
Example HTTP Authentication Request:
POST /api/v2/oauth2/token HTTP/1.1
Host: id.sophos.com
Content-Type: application/x-www-form-urlencoded
Example HTTP Authentication Response:
grant_type=client_credentials&client_id=<Client_ID>&client_secret=<Client_Secret>&scope=token
Example Postman Authentication Request:
3. Building subsequent API requests
Once authenticated, subsequent API requests into Sophos Central may contain the following items
- Unique regional URL where the data is located
- Authorization token and
- Tenant or Partner/Organization ID within the header
Example HTTP Request to retrieve all Tenants of a Partner:
Example HTTP Request to retrieve all Endpoints of a Tenant:
Note the differences between the two requests above. In the URL and Headers where the first call is at the partner level, is a generic URL, and contains the Partner ID. Whereas the second request is at a lower tenant level and contains a specific regional URL, and a Tenant ID.