API Calls

This chapter describes the nSA MSP REST entities and the API calls that can be made to them.

For all API calls, the following CURL command format uses the DSID cookie to query the REST API server:

curl -v --cookie "DSID=<value>" <api_request_url>

MSP API Schemas

The msp API contains the following schema entities:

TenantAdminUserEntity Schema

This schema contains the following structure and properties:

{
   username  string
             First admin username of the tenant

   email     string($email)
             Admin login email address
}

SubscriptionEntity Schema

This schema contains the following structure and properties:

{
   id                string($uuid)
                     Unique identifier of the subscription

   display_name      string
                     The display name for the subscription

   category          string
                     Enum:
                     [ ZTA, PCS ]

   total_users       integer
                     Maximum users count for the subscription

   display_category  string
                     The product category displayed in the MSP portal
}

TenantCreateEntity Schema

This schema contains the following structure and properties:

{
   sub_domain        string
                     Subdomain name of the tenant

   user              $ref
                     TenantAdminUserEntity
                     The admin user instance for the tenant

   name              string
                     Tenant name

   created           string($datetime)
                     Datetime of Tenant creation

   subscriptions     array
                     [ SubscriptionEntity ]
                     A list of subscription entitlements for the tenant
}

TenantUpdateEntity Schema

This schema contains the following structure and properties:

{
   name              string
                     Tenant name

   subscriptions     array
                     [ SubscriptionEntity ]
                     A list of subscription entitlements for the tenant
}

TenantEntity Schema

This schema contains the following structure and properties:

{
   sub_domain        string
                     Subdomain name of the tenant

   user              $ref
                     TenantAdminUserEntity
                     The admin user instance for the tenant


   name              string
                     Tenant name

   created           string($datetime)
                     Date-time of Tenant creation

   subscriptions     array
                     [ SubscriptionEntity ]
                     A list of subscription entitlements for the tenant

   login_url         string
                     Login URL of the Tenant Admin Portal

   status            string
                     Status of the tenant
}

TenantCollectionEntity Schema

This schema contains the following structure and properties:

{
   total             integer
                     Number of MSP owned tenants

   tenants           array
                     [ TenantEntity ]
                     A list of tenants

   users
   {
      ZTA            integer
                     The active users count for the ZTA product

      PCS            integer
                     The active users count for the PCS product
   }

   tenant_stats
   {
      active         integer
                     The number of active tenants

      blocked        integer
                     The number of blocked tenants

      initializing   integer
                     The number of tenants in an "initializing" state
   }

   tenant_cap_limit  integer
                     The maximum number of tenants allowed for this MSP
}

MspTenantUsageReportEntity Schema

This schema contains the following structure and properties:

{
   id                string($uuid)
                     Unique identifier of the Usage Report

   file_name         string
                     Usage Report file name

   created           string($datetime)
                     Date-time of Usage Report creation
}

UsageReportCollectionEntity Schema

This schema contains the following structure and properties:

{
   total             integer
                     Total number of Tenant Usage Reports

   items             array
                     [ MspTenantUsageReportEntity ]
                     A list of Tenant Usage Reports
}

DeleteErrorReportEntity Schema

This schema contains the following structure and properties:

{
   id                string($uuid)
                     Unique identifier of the Usage Report

   file_name         string
                     Usage Report file name
}

DeleteErrorReportCollectionEntity Schema

This schema contains the following structure and properties:

{
   message           string
                     List of file name which are failed to be deleted

   total             integer
                     Total number of Tenant Usage Reports failed to be deleted

   error             array
                     [ DeleteErrorReportEntity ]
                     A list of reports which are failed to be deleted
}

UsageReportDownloadURL Schema

This schema contains the following structure and properties:

{
   url               string($url)
                     The Usage Report download URL
}

UsageReportScheduleEntity Schema

This schema contains the following structure and properties:

{
   frequency         string
                     ( default: daily )
                     Frequency of the schedule (one of 'daily', 'weekly', 'monthly')

   start_day         integer
                     ( default: 1 )
                        1. start_day is ignored if frequency is 'daily'
                        2. start_day must be between 0 (Mon) and 6 (Sun) if frequency is 'weekly'
                        3. start_day must be between 1 and 28 if frequency is 'monthly'

   disabled          boolean
                     Disable the schedule
}

MSP API Methods

The msp API supports the following activities/methods:

Adding a Tenant

To add a new tenant, use the following REST API call:

  • Method: POST /api/msp/tenants

  • Resource: Path

  • JSON Data: JSON dictionary representing a new TenantCreateEntity Schema entity.

Note

You can only continue to use this method while the total number of tenants for this MSP is below the maximum tenant limit. If you hit the limit, consider creating a request to increase the limit (see Creating a Request to Increase the Tenant Limit).

If processed correctly, a HTTP 202 response is returned. Otherwise, a JSON body containing an error is returned.

Request

The following is an example request:

POST /api/msp/tenants
Authorization:
Content-Type: application/json
Request Body

{
  "sub_domain": "string",
  "user": {
    "username": "string",
    "email": "[email protected]"
  },
  "name": "string",
  "created": "string",
  "subscriptions": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "display_name": "string",
      "category": "ZTA",
      "total_users": 0,
      "display_category": "string"
    }
  ]
}

Response

The following is an example response:

HTTP/1.1 202 OK

Retrieving a list of Tenants

To retrieve the list of tenant configurations, use the following REST API call:

  • Method: GET /api/msp/tenants

  • Resource: Path

If processed correctly, a JSON body containing a TenantCollectionEntity Schema entity is returned. Otherwise, a JSON body containing an error is returned.

Parameters

  • start: (integer - in: query)

    The number of initial results that should be skipped. (Default 0)

  • limit: (integer - in: query)

    The number of results that should be returned. (Default 20)

Request

The following is an example request:

GET /api/msp/tenants?start=0&limit=20
Authorization:
Content-Type: application/json

Response

The following is an example response:

HTTP/1.1 200 OK
Content-Type: application/json
Response Body

{
   "total": 0,
   "tenants": [
    {
      "sub_domain": "string",
      "user": {
        "username": "string",
        "email": "[email protected]"
      },
      "name": "string",
      "created": "string",
      "subscriptions": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "display_name": "string",
          "category": "ZTA",
          "total_users": 0,
          "display_category": "string"
        }
      ],
      "login_url": "string",
      "status": "string"
    }
  ],
  "users": {
    "ZTA": 0,
    "PCS": 0
  },
  "tenant_stats": {
    "active": 0,
    "blocked": 0,
    "initializing": 0
  },
  "tenant_cap_limit": 0
}

Creating a Request to Increase the Tenant Limit

To create a request to increase the maximum tenant creation limit, use the following REST API call:

  • Method: POST /api/msp/tenants/requests/tenant-cap-limit

  • Resource: Path

If processed correctly, a JSON body containing the request ID is returned. Otherwise, a JSON body containing an error is returned.

Request

The following is an example request:

POST /api/msp/tenants/requests/tenant-cap-limit
Authorization:
Content-Type: application/json

Response

The following is an example response:

HTTP/1.1 200 OK
Content-Type: application/json
Response Body

{
  "id": "abcdef1ad9424389b788d97337c894a6"
}

Editing a Tenant Configuration

To edit a tenant’s configuration, use the following REST API call:

  • Method: PUT /api/msp/tenants/{tenant_id}

  • Resource: Path

  • JSON Data: JSON dictionary representing a TenantUpdateEntity Schema entity.

If processed correctly, a JSON body containing an updated instance of a TenantUpdateEntity Schema is returned. Otherwise, a JSON body containing an error is returned.

Parameters

  • tenant_id: (string UUID - in: path)

    The ID of the MSP-owned tenant.

Request

The following is an example request:

PUT /api/msp/tenants/627df11ad9424389b788d97337c894a6
Authorization:
Content-Type: application/json
Request Body

{
  "name": "string",
  "subscriptions": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "display_name": "string",
      "category": "ZTA",
      "total_users": 0,
      "display_category": "string"
    }
  ]
}

Response

The following is an example response:

HTTP/1.1 200 OK
Content-Type: application/json
Response Body

{
  "name": "string",
  "subscriptions": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "display_name": "string",
      "category": "ZTA",
      "total_users": 0,
      "display_category": "string"
    }
  ]
}

Generating a new usage summary report

To generate a new usage summary report for all MSP-owned tenants, use the following REST API call:

  • Method: POST /api/msp/reports/usage

  • Resource: Path

If processed correctly, a JSON body containing a MspTenantUsageReportEntity Schema entity is returned. Otherwise, a JSON body containing an error is returned.

Request

The following is an example request:

POST /api/msp/reports/usage
Authorization:
Content-Type: application/json

Response

The following is an example response:

HTTP/1.1 200 OK
Content-Type: application/json
Response Body

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "file_name": "string",
  "created": "string"
}

Retrieving the list of Usage Reports

To retrieve the list of usage reports already generated for this MSP, use the following REST API call:

  • Method: GET /api/msp/reports/usage

  • Resource: Path

If processed correctly, a JSON body containing a UsageReportCollectionEntity Schema entity is returned. Otherwise, a JSON body containing an error is returned.

Parameters

  • start: (integer - in: query)

    The number of initial results that should be skipped. (Default 0)

  • limit: (integer - in: query)

    The number of results that should be returned. (Default 20)

Request

The following is an example request:

GET /api/msp/reports/usage?start=0&limit=20
Authorization:
Content-Type: application/json

Response

The following is an example response:

HTTP/1.1 200 OK
Content-Type: application/json
Response Body

{
  "total": 0,
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "file_name": "string",
      "created": "string"
    }
  ]
}

Deleting a list of Usage Reports

To delete a collection of usage report entities, use the following REST API call:

  • Method: DELETE /api/msp/reports/usage

  • Resource: Path

If processed correctly, a HTTP 204 confirmation is returned. Otherwise, a HTTP 200 response is returned, with a JSON response body containing a DeleteErrorReportCollectionEntity Schema entity (the list of report IDs that were not deleted).

Parameters

  • report_ids: (array[string] - in: query)

    A list of the report IDs to delete

Request

The following is an example request:

DELETE /api/msp/reports/usage?report_ids=e274bf3ebe3841a88ade1630515624c6,e362bf3ebe3841a88ade5823915684c2
Authorization:
Content-Type: application/json

Response

The following is an example response:

HTTP/1.1 204 Successfully deleted usage reports
Content-Type: application/json

Obtaining the URL to Download a Usage Report

To obtain the URL with which you can download a usage report to your local workstation, use the following REST API call:

  • Method: GET /api/msp/reports/usage/{report_id}/download-url

  • Resource: Path

If processed correctly, a JSON body containing a UsageReportDownloadURL Schema entity is returned. Otherwise, a JSON body containing an error is returned.

Parameters

  • report_id: (string UUID - in: path)

    The report ID.

Request

The following is an example request:

GET /api/msp/reports/usage/827df11ad9424389b788d97337c894a8/download-url
Authorization:
Content-Type: application/json

Response

The following is an example response:

HTTP/1.1 200 OK
Content-Type: application/json
Response Body

{
  "url": "string"
}

Creating a Usage Summary Report Schedule

To create a usage summary report schedule for all MSP-owned tenants, use the following REST API call:

If processed correctly, a JSON body containing an updated instance of a UsageReportScheduleEntity Schema entity is returned. Otherwise, a JSON body containing an error is returned.

Request

The following is an example request:

POST /api/msp/reports/usage/schedule
Authorization:
Content-Type: application/json
Request Body

{
  "frequency": "weekly",
  "start_day": 3,
  "disabled": true
}

Response

The following is an example response:

HTTP/1.1 200 OK
Content-Type: application/json
Response Body

{
  "frequency": "weekly",
  "start_day": 3,
  "disabled": true
}

Retrieving the Usage Report Schedule

To retrieve the usage report schedule for this MSP, use the following REST API call:

  • Method: GET /api/msp/reports/usage/schedule

  • Resource: Path

If processed correctly, a JSON body containing the UsageReportScheduleEntity Schema entity is returned. Otherwise, a JSON body containing an error is returned.

Request

The following is an example request:

GET /api/msp/reports/usage/schedule
Authorization:
Content-Type: application/json

Response

The following is an example response:

HTTP/1.1 200 OK
Content-Type: application/json
Response Body

{
  "frequency": "weekly",
  "start_day": 3,
  "disabled": true
}