Skip to content

Guide

Overview

This guide helps you use the Admin API to manage administrators and roles to which they can be assigned.

Pre-requisites

You must go through the Getting Started guide. This helps you set up your API credentials.

The instructions in this guide assume you have authenticated using API credentials and obtained a valid JWT token ({jwt}). You should also have the UUID of the account that you can pass to each API call ({tenantId}). This is returned by the Who-am-I API.

Terminology

Before you use this API, here are a few terms you should know:

  • Principal: A user or service associated with a single Sophos Fusion account that requires access to resources in that account.
  • Administrator: A user principal with a unique identity (email address).
  • API credentials: A service principal with a unique identity (Client ID)
  • Permission set: A set of operations that a principal can do.
  • Role: A collection of permission sets. Roles may be predefined by Sophos or custom.
  • Role assignment: The assignment of role to a principal. A principal must have exactly one role assignment at any given time.

API operations

You can perform the following operations using the Tenant API:

Operation HTTP Method Path
List permission sets GET /common/v1/roles/permission-sets
List all tenant roles GET /common/v1/roles
Create a new tenant role POST /common/v1/roles
Get a tenant role by ID GET /common/v1/roles/{roleId}
Update an existing tenant role PATCH /common/v1/roles/{roleId}
Delete a tenant role by ID DELETE /common/v1/roles/{roleId}
List all tenant administrators GET /common/v1/admins
Create a new tenant administrator POST /common/v1/admins
Get a tenant administrator by ID GET /common/v1/admins/{adminId}
Delete a tenant administrator by ID DELETE /common/v1/admins/{adminId}
Assign a role to a tenant administrator POST /common/v1/admins/{adminId}/role-assignments
Get the list of role assignments for an administrator GET /common/v1/admins/{adminId}/role-assignments
Get tenant administrator role assignment by ID GET /common/v1/admins/{adminId}/role-assignments/{assignmentId}
Remove a role assignment from a tenant administrator DELETE /common/v1/admins/{adminId}/role-assignments/{assignmentId}

Note: The base URL for all the API calls above is https://api.central.sophos.com.

List permission sets

Call this API to get a list of permission sets:

GET /common/v1/roles/permission-sets
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

The response looks like this:

{
    "items": [
        {
            "id": "tenant_role_management",
            "name": "Tenant Role Management",
            "description": "Provides management access for tenant roles",
            "type": "setting",
            "access": "admin",
            "principalTypes": [
                "service"
            ],
            "allowedInCustomRoles": true
        },
        {
            "id": "logs_reports_readonly",
            "name": "Logs Reports Readonly",
            "description": "Provides read-only access for logs & reports",
            "type": "setting",
            "principalTypes": [
                "user",
                "service"
            ],
            "allowedInCustomRoles": true
        },
        // Other permission sets
    ]
}

You need the id values of permission sets to create custom roles.

List all tenant roles

To fetch a list of roles, call:

GET /common/v1/roles
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

This returns a response like:

{
    "items": [
        {
            "id": "70617274-6e65-7273-7570-657261646d69",   // Role ID
            "name": "TenantSuperAdmin",
            "description": "Tenant SuperAdmin",
            "type": "predefined",               // May be 'predefined' or 'custom'
            "principalType": "user",            // May be 'user' or 'service'
            "permissionSets": [
                "wireless_product_admin",       // Permission set ID
                "policy_mgmt_admin",
                "optix_product_management",
                "phish_threat_product_admin",
                // ... other permission sets
            ]
        },
        {
            "id": "70617274-6e65-7268-656c-706465736b5b",
            "name": "TenantHelpDesk",
            "description": "Tenant HelpDesk",
            "type": "predefined",
            "principalType": "user",
            "permissionSets": [
                "wireless_product_helpdesk",
                "policy_mgmt_readonly",
                "optix_product_helpdesk",
                "phish_threat_product_helpdesk",
                // ... other permission sets
            ]
        },
        // ... other role objects
    ]
}

Create a new tenant role

To create a new custom role:

POST /common/v1/roles
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

Send a JSON request body shaped like this:

{
    "name": "My custom role",       // Required; role name must be unique
    "permissionSets": [             // Required; at least one permission
        "wireless_product_helpdesk" //   set must be given
    ],
    "principalType": "user",        // Required
    "description": "WiFi helpdesk role"
}

The response looks like:

{
    "id": "67f37457-757e-41b7-8cd1-94336a109262",
    "name": "My custom role",
    "description": "Gives helpdesk access only to WiFi management functionality",
    "type": "custom",
    "principalType": "user",
    "permissionSets": [
        "wireless_product_helpdesk"
    ],
    "createdAt": "2021-08-08T06:21:44.750Z",
    "updatedAt": "2021-08-08T06:21:44.750Z"
}

This role shows up in the response to the API call to list roles. Note the type is set to custom.

Get a tenant role by ID

When you know the role ID, get the role object by calling:

GET /common/v1/roles/{roleId}
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

The response is a role object with the same attributes as an item in the response returned by the List roles API operation.

Update an existing tenant role

To modify an existing custom role:

PATCH /common/v1/roles/{roleId}
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

Pass the role ID in place of {roleId}

Send a request body that looks like this:

{
    "name": "Custom Role 2",                     // Updated name; must be unique
    "description": "My custom role description", // Updated description
    "permissionSets": [                          // Updated permission set
        "optix_product_management",              //   (replaces existing ones)
        "phish_threat_product_admin",
        // ... other permission sets
    ]
}

All fields are optional. Some permission sets are restricted from use in custom roles. These have the field allowedInCustomRole set to false (see List permission sets).

The response is a role object.

Delete a tenant role by ID

Delete a custom role by calling:

DELETE /common/v1/roles/{roleId}
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

The response indicates if the role was deleted. Note you can't delete a role that is in use.

List all tenant administrators

To list administrators in the tenant account, call the API:

GET /common/v1/admins
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

The response is paged and looks like this:

{
    "items": [   // Array of administrator objects
        {
            "id": "44df3918-3587-4635-a53c-e9dbeb79b3b7",
            "users": [
                {
                    "id": "a7ab4666-8524-400f-955b-3b8df48d2c95",
                    "name": "Joe Bloggs"
                }
            ],
            "profile": {
                "name": "Joe Bloggs",
                "firstName": "Joe",
                "lastName": "Bloggs",
                "email": "joe.bloggs@example.com"
            },
            "roleAssignments": [
                {
                    "id": "2dc99f0c-e9bd-4bb5-85c5-3b9a013be92c",
                    "roleId": "70617274-6e65-7272-6561-646f6e6c795b"
                }
            ]
        },
        // ...other administrators
    ],
    "pages": {
        "current": 1,
        "size": 50,
        "maxSize": 100
    }
}

You can set the page size using pageSize=50. Use page=2 to fetch the second page. Pass the query param pageTotal=true to get number of administrators across all the pages in the pagination metadata in the response.

Create a new tenant administrator

To promote an existing user to an administrator, call the API:

POST /common/v1/admins
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

Pass the request body:

{
    "userId": "a7ab4666-8524-400f-955b-3b8df48d2c95",  // Required
    "roleAssignments": [    // Required; must contain exactly one object
        {
            "roleId": "70617274-6e65-7272-6561-646f6e6c795b"  // Required; predefined or custom role ID
        }
    ]
}

The response is an administrator object:

{
    "id": "44df3918-3587-4635-a53c-e9dbeb79b3b7",
    "users": [
        {
            "id": "a7ab4666-8524-400f-955b-3b8df48d2c95",
            "name": "Joe Bloggs"
        }
    ],
    "profile": {
        "name": "Joe Bloggs",
        "firstName": "Joe",
        "lastName": "Bloggs",
        "email": "joe.bloggs@example.com"
    },
    "roleAssignments": [
        {
            "id": "2dc99f0c-e9bd-4bb5-85c5-3b9a013be92c",
            "roleId": "70617274-6e65-7272-6561-646f6e6c795b"
        }
    ]
}

Get a tenant administrator by ID

To get a tenant administrator's details by ID, call:

GET /common/v1/admins/{adminId}
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

The response is an administrator object, like the Create administrator API call.

Delete a tenant administrator by ID

To remove a user's administrator access by ID, call:

DELETE /common/v1/admins/{adminId}
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

The response indicates that the administrator access was removed for this user.

Note: this API call does not delete the user.

Assign a role to a tenant administrator

To assign a role to an existing administrator, call:

POST /common/v1/admins/{adminId}/role-assignments
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

Pass the administrator's ID in place of {adminId}.

The request body should look like this:

{
    "roleId": "70617274-6e65-7272-6561-646f6e6c795b"
}

Get the list of role assignments for an administrator

If you have an administrator's ID, you can list their role assignments by calling:

GET /common/v1/admins/{adminId}/role-assignments
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

The response looks like this:

{
    "items": [
        {
            "id": "2dc99f0c-e9bd-4bb5-85c5-3b9a013be92c",
            "roleId": "70617274-6e65-7272-6561-646f6e6c795b"
        }
    ]
}

Get tenant administrator role assignment by ID

If you know an administrator's ID and the ID of one of their role assignments, you can retrieve the role assignment details using:

GET /common/v1/admins/{adminId}/role-assignments/{roleAssignmentId}
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

The response is a role assignment object, like the Create role assignment API call.

Remove a role assignment

To remove a role assigned to an administrator, you need to delete the related role assignment by ID.

DELETE /common/v1/admins/{adminId}/role-assignments/{roleAssignmentId}
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

Limitations

You can't use this API to modify an administrator's profile.

Additional resources

You can download the Postman collection for this API here. For further details, read the API reference.