Manage Sophos Central API credentials securely
Sophos Central can be automated through APIs and connected to SIEM, RMM, reporting, or insurance platforms. These integrations should use dedicated API Credentials, consisting of a Client ID and Client Secret, rather than personal administrator accounts.
These credentials are machine identities. Anyone who has the secret can perform every API action permitted by the assigned service principal role. A secret must therefore be treated like a privileged password and must never appear in scripts, tickets, emails, or Git repositories.
Distinguish API Credentials from Integration Credential Manager
Under Global Settings > Access Control, Central provides two areas with similar names:
| Area | Purpose |
|---|---|
| API Credentials | Machine identity that an application uses to call the Sophos Central APIs |
| Integration Credential Manager | Credentials for third-party products that Sophos uses for integrations such as Data Ingestion or Response Actions |
Create API Credentials for an in-house script, SIEM query, or API client. Credentials for a third-party product that Sophos Central itself needs to use belong in Integration Credential Manager.
Not every automation task requires general API credentials: synchronize users and groups through a directory service, and deploy software through an installer script executed locally on each device. Create an API identity for AD Sync only when the intended synchronization workflow calls for it, and assign only Service Principal Directory Sync.
Prerequisites and ownership
Only a Super Admin can create and manage API credentials. The application authenticates with its own Client ID and Client Secret, not with the personal administrator account.
Before creating it, document the purpose, owner, target system, required role, expiration date, and emergency contact. Use a separate credential for each application and environment. Sharing one secret among a backup script, SIEM, and external service provider prevents targeted revocation and makes root-cause analysis difficult.
Choose the appropriate service principal role
Sophos provides several roles:
- Service Principal Read-Only can read tenant data, but cannot modify it or run Live Discover queries.
- Service Principal Management can query, create, modify, and delete users and user groups; query and act on alerts; query endpoints and trigger actions such as scans; and view or modify global Endpoint Protection settings. It also manages administrators, roles, and security policies, but has no Live Discover query access.
- Service Principal Forensics creates, views, runs, and deletes Live Discover queries.
- Service Principal Directory Sync is exclusively for Active Directory synchronization and cannot perform other API tasks.
- Service Principal Firewall restricts the identity to firewall management and prevents Central API tasks outside that scope.
- Service Principal Audit Log gives external applications, SIEM tools, and integration scripts read-only query access to retrieve audit log events.
- Service Principal Super Admin has broad read, write, delete, and query permissions.
Always start with the narrowest role. A reporting or cyber-insurance integration receives Read-Only. AD Sync receives its dedicated role. Use Super Admin only when documented API endpoints genuinely require broad write permissions and no narrower role works.
Create a credential
The path is Global Settings > Access Control > API Credentials. The terms of use must be accepted on first access.
- Open Add Credential.
- Enter a unique name and a description that identifies the application, environment, and owner.
- Select the minimum required service principal role.
- Create the credential and immediately record the Client ID and Client Secret.
- Store the secret in an enterprise secret store and clear any temporary clipboard or working copy.
The Client Secret is displayed only once and cannot be revealed later. If it is lost, do not attempt to recover the existing secret. Create a new credential and delete the old one after a successful cutover.
Test authentication in a controlled manner
The first test must not be a production write action. First obtain an OAuth access token from the Sophos identity endpoint. The whoami endpoint then returns the tenant ID, API host, and account data type. Only then perform a harmless read request against the API host supplied for that tenant.
Do not copy an API host from an example. Sophos operates multiple data regions, so the URL returned by whoami must be used. Tenant ID and organization ID are also not interchangeable.
Document at least these test cases:
- Authentication with the new identity succeeds.
- The expected tenant is returned.
- Permitted read operations succeed.
- A prohibited operation is rejected with
403 Forbidden. - The target system records the test traceably without logging the Client Secret.
Operate expiration and rotation
Sophos does not send a warning when an API credential expires. Once expired, it can no longer authenticate and is automatically removed from Central. Expiration monitoring must therefore take place outside Central.
A clean rotation process uses a short overlap:
- Create a new credential with the same or a narrower role.
- Move the application to the new Client ID and secret.
- Test authentication and the application’s business function.
- Delete the old credential.
- Verify the change in the secret register and operating documentation.
Do not leave the old credential active for months as a precaution. If an application supports only one secret set, schedule a maintenance window.
Replace legacy SIEM API tokens
API Token Management is the former authentication method for the SIEM Integration API. Sophos no longer issues new tokens there and does not extend existing lifetimes. Existing tokens work only until they expire.
Do not leave an integration on this method until the last day. Inventory its token, target system, expiration date, and endpoints; create an appropriate API credential; migrate the application; and verify the complete data flow. Remove the old token only after successful parallel verification.
Moving from a legacy token to API credentials is more than a rename. The integration must support OAuth authentication, whoami, the regional host, and the role model. Configure a SIEM connector from its current vendor instructions, not from an old token example.
External service providers and third-party access
Create a dedicated Service Principal Read-Only identity for an external party when read access is sufficient. Transfer the Client ID and secret through separate, encrypted channels. Record a firm end date and delete the access when the project ends.
Through the API, such third-party access can read Alerts and Events, Account Health Check results, device details, and policy configurations. Read-Only prevents adding, changing, and deleting data in Central, but does not limit what readable data the third-party platform retrieves or stores. Before approval, contractually define data scope, purpose, storage location, retention, and deletion.
Creation follows Global Settings > Access Control > API Credentials > Add Credential. Accept the use and privacy terms on first access, select Service Principal Read-Only, and immediately secure the Client ID and the one-time Client Secret. Transfer them through an approved encrypted channel, such as the provider’s HTTPS portal, never by email or in ticket text.
Do not copy the API host from a static regional table. The application must use whoami to discover the API host valid for that specific tenant. This keeps the integration correct even if Sophos changes regions or endpoints. Delete the credential as soon as the third party no longer needs access; this immediately revokes the API authorization.
Exporting a personal Super Admin account, sharing one API identity across customers, or placing a secret in a support ticket is unacceptable. The service provider must also disclose where the secret is stored, how it is protected, and when it is deleted.
Troubleshoot methodically
401 Unauthorized
The Client ID, secret, token endpoint, or OAuth request is usually incorrect. An expired and already removed credential produces the same error. First verify that the credential still exists in Central and that the application uses the latest secret set.
403 Forbidden
Authentication succeeded, but the role does not permit the action. Instead of immediately granting Super Admin, map the required API endpoint to the appropriate service principal role.
Correct token, wrong data region
The access token alone does not select the business API host. The application must use the regional host returned by whoami. A hard-coded host from another region causes errors or queries across the wrong platform boundary.
Integration fails without a warning
If Central has no open alert, check the expiration date, last successful API request, and secret version in the target system. Expiration monitoring belongs in external monitoring.
Regular review
At least quarterly, review the name, owner, role, last use, expiration, and target system of every credential. Delete identities that cannot be assigned or are no longer used. If secret exposure is suspected, immediately delete the affected credential and replace it. Then inspect the target-system and integration logs for unusual API calls.
Review personal administrator permissions separately according to Assign Sophos Central administrator roles correctly. API credentials replace neither MFA nor personal, accountable administrator access.