Getting started

Overview¶

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

Pre-requisites¶

You must go through the Getting Started guide for Sophos organizations. 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 organization account that you can pass to each API call ({organizationId}). 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 system-wide unique identity (email address).
API credentials: A service principal with a system-wide unique identity (Client ID).
Permission set: A cohesive set of operations that a principal can perform.
Role: A collection of permission sets. Roles may be predefined by Sophos or custom.
Scope: A set of accounts that contain the resources to which a principal is given access.
Role assignment: The assignment of a role to a principal within an associated scope. An administrator has zero or more role assignments.

A role assignment associates a role with a scope that determines which accounts the role applies to. The scope type may be one of:

tenant: a single tenant, identified by its id.
tenantGroup: a group of tenants, identified by the tenant group's id.
allManagedTenants: a dynamic scope that includes all current and future tenants managed by the organization.
self: the organization's own account.

Note that role assignments only confer privileges, never take them away. The result of multiple role assignments is therefore always additive.

API operations¶

You can perform the following operations using the Organization API:

Operation	HTTP Method	Path
List permission sets	`GET`	`/organization/v1/roles/permission-sets`
List all roles	`GET`	`/organization/v1/roles`
Create a new role	`POST`	`/organization/v1/roles`
Get a role by ID	`GET`	`/organization/v1/roles/{roleId}`
Update an existing role	`PATCH`	`/organization/v1/roles/{roleId}`
Delete a role by ID	`DELETE`	`/organization/v1/roles/{roleId}`
List all administrators	`GET`	`/organization/v1/admins`
Create a new administrator	`POST`	`/organization/v1/admins`
Get an administrator by ID	`GET`	`/organization/v1/admins/{adminId}`
Remove an administrator	`DELETE`	`/organization/v1/admins/{adminId}`
List role assignments for an administrator	`GET`	`/organization/v1/admins/{adminId}/role-assignments`
Assign a role to an administrator	`POST`	`/organization/v1/admins/{adminId}/role-assignments`
Get an administrator role assignment by ID	`GET`	`/organization/v1/admins/{adminId}/role-assignments/{assignmentId}`
Remove a role assignment from an administrator	`DELETE`	`/organization/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 /organization/v1/roles/permission-sets
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

The response looks like this:

{
    "items": [
        {
            "id": "enterprise_admin",
            "name": "Enterprise Admin",
            "description": "Provides full management access at the organization level",
            "type": "setting",
            "access": "admin",
            "principalTypes": [
                "user",
                "service"
            ],
            "allowedInCustomRoles": true
        },
        {
            "id": "endpoint_product_admin",
            "name": "Endpoint Product Admin",
            "description": "Provides management access for the endpoint product",
            "type": "product",
            "access": "admin",
            "principalTypes": [
                "user",
                "service"
            ],
            "allowedInCustomRoles": true
        }
        // Other permission sets
    ]
}

You will need the id values of permission sets to be able to create custom roles. Some permission sets are restricted from use in custom roles; these have the field allowedInCustomRoles set to false.

List all roles¶

To fetch a list of roles, call:

GET /organization/v1/roles
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

This returns a response like:

{
    "items": [
        {
            "id": "2b8f2624-b054-45e0-923e-6527d9054342",   // Role ID
            "name": "OrganizationSuperAdmin",
            "description": "Organization Super Admin",
            "type": "predefined",               // May be 'predefined' or 'custom'
            "principalType": "user",            // May be 'user' or 'service'
            "permissionSets": [
                "enterprise_admin",             // Permission set ID
                "endpoint_product_admin"
                // ... other permission sets
            ]
        },
        // ... other role objects
    ]
}

You can filter the results using the roleType (predefined or custom) and principalType (user or service) query parameters.

Create a new role¶

To create a new custom role:

POST /organization/v1/roles
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

Send a JSON request body shaped like this:

{
    "name": "Organization custom role",   // Required; role name must be unique
    "description": "Organization custom role",
    "principalType": "user",              // Required; 'user' or 'service'
    "permissionSets": [                   // Required; at least one permission
        "enterprise_admin",               //   set must be given
        "endpoint_product_admin"
    ]
}

The response looks like:

{
    "id": "67f37457-757e-41b7-8cd1-94336a109262",
    "name": "Organization custom role",
    "description": "Organization custom role",
    "type": "custom",
    "principalType": "user",
    "permissionSets": [
        "enterprise_admin",
        "endpoint_product_admin"
    ],
    "createdAt": "2026-06-02T06:21:44.750Z",
    "updatedAt": "2026-06-02T06:21:44.750Z"
}

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

Get a role by ID¶

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

GET /organization/v1/roles/{roleId}
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

Pass the role ID in place of {roleId}. 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 role¶

To modify an existing custom role:

PATCH /organization/v1/roles/{roleId}
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

Pass the role ID in place of {roleId}.

Send a request body that looks like this:

{
    "name": "Organization custom role",          // Updated name; must be unique
    "description": "Organization custom role",    // Updated description
    "permissionSets": [                           // Replaces existing permission sets
        "enterprise_admin",
        "endpoint_product_admin"
    ]
}

All fields are optional. Alternatively, you can add and remove permission sets incrementally instead of replacing them:

{
    "permissionSets": {
        "add": [
            "enterprise_admin",
            "endpoint_product_admin"
        ],
        "remove": [
            "firewall"
        ]
    }
}

The response is the updated role object.

Delete a role by ID¶

Delete a custom role by calling:

DELETE /organization/v1/roles/{roleId}
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

The response indicates if the role was deleted:

{
    "deleted": true
}

Note that you can't delete a predefined role or a role that is currently assigned to an administrator.

List all administrators¶

To list administrators in the organization, call:

GET /organization/v1/admins
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

The response is paged and looks like this:

{
    "items": [   // Array of administrator objects
        {
            "id": "a1c7aa85-7863-4561-a50e-2b345b0e16e7",
            "username": "john.smith@example.com",
            "profile": {
                "name": "John J. Smith",
                "firstName": "John",
                "lastName": "Smith"
            },
            "active": true,
            "primary": false,
            "roleAssignments": [
                {
                    "id": "0b8f2624-b054-45e0-923e-6527d9054342",
                    "roleId": "2b8f2624-b054-45e0-923e-6527d9054342",
                    "scope": {
                        "type": "self"
                    }
                }
            ]
        }
        // ... other administrators
    ],
    "pages": {
        "current": 1,
        "total": 1,
        "items": 2,
        "size": 50,
        "maxSize": 100
    }
}

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

Create a new administrator¶

To create a new administrator, call:

POST /organization/v1/admins
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

Pass the request body:

{
    "username": "john.smith@example.com",   // Required; must be unique
    "profile": {                            // Required
        "name": "John J. Smith",            // Required
        "firstName": "John",                // Required
        "lastName": "Smith",                // Required
        "phone": "12312341234",             // Optional, but recommended
        "mobile": "12312341234",            // Optional
        "fax": "12312341235"                // Optional
    },
    "roleAssignments": [
        {
            "roleId": "70617274-6e65-7273-7570-657261646d69",  // Required; predefined or custom role ID
            "scope": {                                         // Required
                "type": "tenant",                              // 'tenant', 'tenantGroup', 'allManagedTenants' or 'self'
                "id": "004ee2e9-9497-4f58-b4ba-c2fc46b2d187"   // Required if 'type' is 'tenant' or 'tenantGroup'
            }
        }
        // ... other role assignments
    ]
}

The response is an administrator object:

{
    "id": "a1c7aa85-7863-4561-a50e-2b345b0e16e7",
    "username": "john.smith@example.com",
    "profile": {
        "name": "John J. Smith",
        "firstName": "John",
        "lastName": "Smith"
    },
    "active": true,
    "primary": false,
    "roleAssignments": [
        {
            "id": "0b8f2624-b054-45e0-923e-6527d9054342",
            "roleId": "70617274-6e65-7273-7570-657261646d69",
            "scope": {
                "type": "tenant",
                "id": "004ee2e9-9497-4f58-b4ba-c2fc46b2d187"
            }
        }
    ]
}

An administrator needs to be given separate access to each individual tenant through an explicit role assignment with scope type set to tenant and id set to the tenant's ID. To grant access to a group of tenants, use scope type tenantGroup with the tenant group's id.

If the administrator is expected to have implicit access to all tenants managed by the organization, use the scope type allManagedTenants. For an administrator to be allowed to manage the organization's own account, they need a role assignment with the scope type set to self.

Get an administrator by ID¶

To get an administrator's details by ID, call:

GET /organization/v1/admins/{adminId}
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

Pass the administrator's ID in place of {adminId}. The response is an administrator object, the same as that returned by the Create administrator API call.

Remove an administrator¶

To remove an administrator, call:

DELETE /organization/v1/admins/{adminId}
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

The response indicates if the administrator was removed:

{
    "deleted": true
}

Note that you can't remove the last Super admin of the organization.

List role assignments for an administrator¶

With an administrator's ID in hand, you can list their role assignments by calling:

GET /organization/v1/admins/{adminId}/role-assignments
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

The response looks like this:

{
    "items": [
        {
            "id": "0b8f2624-b054-45e0-923e-6527d9054342",
            "roleId": "2b8f2624-b054-45e0-923e-6527d9054342",
            "scope": {
                "type": "self"
            }
        },
        {
            "id": "637aa3cb-18ca-4332-9d57-72dfdf22d779",
            "roleId": "e074b5ec-f637-4dd7-a6bf-6698aa04d73c",
            "scope": {
                "type": "allManagedTenants"
            }
        }
        // ... other role assignments
    ]
}

Assign a role to an administrator¶

To assign a role to an existing administrator, call:

POST /organization/v1/admins/{adminId}/role-assignments
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

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

The request body should look like this:

{
    "roleId": "2b8f2624-b054-45e0-923e-6527d9054342",
    "scope": {
        "type": "tenant",
        "id": "004ee2e9-9497-4f58-b4ba-c2fc46b2d187"
    }
}

The response is the created role assignment object.

Get an administrator role assignment by ID¶

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

GET /organization/v1/admins/{adminId}/role-assignments/{assignmentId}
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

The response is a role assignment object, the same as that returned by the Assign a role API call.

Remove a role assignment¶

To remove a role assigned to an administrator, delete the related role assignment by ID:

DELETE /organization/v1/admins/{adminId}/role-assignments/{assignmentId}
Authorization: Bearer {jwt}
X-Organization-ID: {organizationId}

Limitations¶

This API doesn't allow you to modify administrator profile information. You also can't delete a predefined role, delete a role that is currently assigned to an administrator, or remove the last Super admin of the organization.

Additional resources¶

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