API Calls

This chapter describes the 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 nam created
string($datetime)Datetime of Tenant creation subscriptions array
[ SubscriptionEntity ] A list of subscription entitlements for the tenant }

•See also: TenantAdminUserEntity Schema

•See also: SubscriptionEntity Schema

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 strin
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 }

See also: MspTenantUsageReportEntity Schema

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
booleanDisable 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.

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 ).

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:

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

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:

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 }