Sophos User Management API Guide

Auth method: OAuth 2.0 Client Credentials

Setup steps

1. Log in to Sophos Central as an administrator.
2. Navigate to Global Settings > API Credentials Management.
3. Click 'Add Credential', provide a name, and select the appropriate role (e.g., Super Admin or Service Principal).
4. Copy the generated Client ID and Client Secret.
5. POST to https://id.sophos.com/api/v2/oauth2/token with grant_type=client_credentials, client_id, and client_secret to obtain a Bearer token.
6. Call GET https://api.central.sophos.com/whoami/v1 to retrieve your tenant ID and the region-specific API host (e.g., https://api-{region}.central.sophos.com).
7. Use the region-specific base URL and include the Bearer token in the Authorization header and X-Tenant-ID header for all subsequent requests.

Required scopes

List users

• Method: GET
• URL: https://api-{region}.central.sophos.com/common/v1/directory/users
• Watch out for: Must resolve region-specific base URL via /whoami/v1 first. Use pageFromKey from pages.nextKey for cursor pagination.

Request example

GET /common/v1/directory/users?pageSize=50
Authorization: Bearer {token}
X-Tenant-ID: {tenantId}

Response example

{
  "items": [
    {"id":"uuid","name":"Jane Doe","email":"jane@example.com"}
  ],
  "pages": {"size":50,"total":120,"nextKey":"abc123"}
}

Get user by ID

• Method: GET
• URL: https://api-{region}.central.sophos.com/common/v1/directory/users/{userId}
• Watch out for: Returns 404 if user does not exist in the tenant specified by X-Tenant-ID.

Request example

GET /common/v1/directory/users/{userId}
Authorization: Bearer {token}
X-Tenant-ID: {tenantId}

Response example

{
  "id": "uuid",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "groups": [{"id":"grp-uuid","name":"Finance"}]
}

Create user

• Method: POST
• URL: https://api-{region}.central.sophos.com/common/v1/directory/users
• Watch out for: Email must be unique per tenant. AD-synced tenants may reject manual user creation for AD-managed users.

Request example

POST /common/v1/directory/users
Authorization: Bearer {token}
X-Tenant-ID: {tenantId}
Content-Type: application/json

{"name":"Jane Doe","email":"jane@example.com"}

Response example

{
  "id": "new-uuid",
  "name": "Jane Doe",
  "email": "jane@example.com"
}

Update user

• Method: PATCH
• URL: https://api-{region}.central.sophos.com/common/v1/directory/users/{userId}
• Watch out for: Users sourced from Active Directory or Azure AD may be read-only via API; updates may be rejected.

Request example

PATCH /common/v1/directory/users/{userId}
Authorization: Bearer {token}
X-Tenant-ID: {tenantId}
Content-Type: application/json

{"name":"Jane Smith"}

Response example

{
  "id": "uuid",
  "name": "Jane Smith",
  "email": "jane@example.com"
}

Delete user

• Method: DELETE
• URL: https://api-{region}.central.sophos.com/common/v1/directory/users/{userId}
• Watch out for: Deleting a user does not automatically remove associated endpoint assignments or policies.

Request example

DELETE /common/v1/directory/users/{userId}
Authorization: Bearer {token}
X-Tenant-ID: {tenantId}

Response example

HTTP 204 No Content

List user groups

• Method: GET
• URL: https://api-{region}.central.sophos.com/common/v1/directory/user-groups
• Watch out for: Group membership changes may take time to propagate to policy enforcement.

Request example

GET /common/v1/directory/user-groups?pageSize=50
Authorization: Bearer {token}
X-Tenant-ID: {tenantId}

Response example

{
  "items": [
    {"id":"grp-uuid","name":"Finance","description":"Finance team"}
  ],
  "pages": {"size":50,"total":5}
}

Add user to group

• Method: POST
• URL: https://api-{region}.central.sophos.com/common/v1/directory/user-groups/{groupId}/users
• Watch out for: Batch add; invalid user IDs are reported in errors array rather than failing the entire request.

Request example

POST /common/v1/directory/user-groups/{groupId}/users
Authorization: Bearer {token}
X-Tenant-ID: {tenantId}
Content-Type: application/json

{"ids":["user-uuid-1","user-uuid-2"]}

Response example

{
  "addedCount": 2,
  "errors": []
}

Resolve tenant context (whoami)

• Method: GET
• URL: https://api.central.sophos.com/whoami/v1
• Watch out for: Must be called before any tenant-scoped API call to obtain the correct dataRegion host. Using the wrong regional host returns 403 or 404.

Request example

GET /whoami/v1
Authorization: Bearer {token}

Response example

{
  "id": "tenant-uuid",
  "idType": "tenant",
  "apiHosts": {
    "global": "https://api.central.sophos.com",
    "dataRegion": "https://api-us01.central.sophos.com"
  }
}

• Rate limits: Sophos Central API enforces rate limits but does not publicly document specific numeric thresholds per plan in official docs. Exceeding limits returns HTTP 429.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: Official docs do not specify rate-limit headers or Retry-After behavior. Implement exponential backoff on HTTP 429 responses.
• Pagination method: cursor
• Default page size: 50
• Max page size: 100
• Pagination pointer: pageFromKey

• Webhooks available: No
• Webhook notes: Sophos Central API does not offer a native webhook/push notification system for user-management events as of the current documentation.
• Alternative event strategy: Poll the directory/users endpoint periodically to detect changes, or use Sophos SIEM integration / event streaming for security events (not user provisioning events).

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A
• Endpoint: Not documented

Limitations:

• Sophos Central does not expose a native SCIM 2.0 endpoint.
• User provisioning from Okta is available via the Okta Sophos connector (SAML/SSO-based provisioning), not a standards-based SCIM endpoint.
• Microsoft Entra ID integration is available for SSO but SCIM provisioning is not documented as natively supported.

Three core automation scenarios are supported by the directory API.

For provisioning, POST to /common/v1/directory/users to create the user record, then POST to /common/v1/directory/user-groups/{groupId}/users to assign group membership - capture the returned user UUID from the creation response before the group call.

For offboarding, locate the user UUID via GET /common/v1/directory/users?search={email}, then DELETE /common/v1/directory/users/{userId};

note that deletion does not uninstall Sophos agents from the user's devices or revoke active endpoint sessions - endpoint cleanup is a separate operation against the endpoint management API.

For bulk enumeration, use GET /common/v1/directory/users?pageSize=100 and follow the cursor: if pages.nextKey is present in the response, pass it as pageFromKey on the next request;

continue until pages.nextKey is absent.

Cursor values are opaque strings - do not attempt to construct or increment them.

For identity graph use cases, the user object exposes source (indicating activeDirectory, azureActiveDirectory, or sophosCentral origin), exchangeLogin, groups array, and tenant context, giving you the fields needed to correlate Sophos user records against upstream identity providers in a unified identity graph.

Provision a new user and assign to a group

1. POST to https://id.sophos.com/api/v2/oauth2/token to obtain Bearer token.
2. GET https://api.central.sophos.com/whoami/v1 to retrieve tenantId and dataRegion host.
3. POST to https://api-{region}.central.sophos.com/common/v1/directory/users with name and email to create the user; capture returned id.
4. GET https://api-{region}.central.sophos.com/common/v1/directory/user-groups to find the target group UUID.
5. POST to https://api-{region}.central.sophos.com/common/v1/directory/user-groups/{groupId}/users with {"ids":["new-user-uuid"]} to add user to group.

Watch out for: If the tenant uses AD sync, the user may need to be created in AD first and will appear in Sophos after sync; direct API creation may be rejected.

Deprovision a user (offboarding)

1. Obtain Bearer token and resolve dataRegion via /whoami/v1.
2. GET /common/v1/directory/users?search={email} to locate the user's UUID.
3. DELETE /common/v1/directory/users/{userId} to remove the user from Sophos Central.
4. Verify endpoint devices previously assigned to the user are reassigned or decommissioned via the endpoint management API separately.

Watch out for: Deleting the user record does not automatically uninstall Sophos agents from their devices or revoke active sessions; endpoint cleanup is a separate operation.

Bulk list all users with pagination

1. Obtain Bearer token and resolve dataRegion via /whoami/v1.
2. GET /common/v1/directory/users?pageSize=100 - process items array.
3. If pages.nextKey is present in the response, repeat GET /common/v1/directory/users?pageSize=100&pageFromKey={nextKey}.
4. Continue until pages.nextKey is absent or null.

Watch out for: pageFromKey values are opaque cursor strings; do not attempt to construct or increment them manually.

Several non-obvious constraints will break integrations if not handled upfront. Users synchronized from Active Directory or Azure AD are typically read-only via the REST API; create, update, and delete operations on AD-sourced users may return 400 or 409 - for AD-managed tenants, user lifecycle must be driven from the directory, not from Sophos.

Sophos Central has no native SCIM 2.0 endpoint; the Okta connector uses SAML/SSO-based provisioning, not a standards-based SCIM flow, so any SCIM assumptions in your tooling will not apply. Rate limits are not publicly documented - the API returns HTTP 429 on breach with no Retry-After header, so implement exponential backoff unconditionally.

Finally, deleting an admin account that owns active API credentials immediately invalidates those tokens; any integration running under that credential will fail silently until re-credentialed.