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, see TenantAdminUserEntity Schema.
SubscriptionEntity, see SubscriptionEntity Schema.
TenantCreateEntity, see TenantCreateEntity Schema.
TenantUpdateEntity, see TenantUpdateEntity Schema.
TenantEntity, see TenantEntity Schema.
TenantCollectionEntity, see TenantCollectionEntity Schema.
MspTenantUsageReportEntity, see MspTenantUsageReportEntity Schema.
UsageReportCollectionEntity, see UsageReportCollectionEntity Schema.
DeleteErrorReportEntity, see DeleteErrorReportEntity Schema.
DeleteErrorReportCollectionEntity, see DeleteErrorReportCollectionEntity Schema.
UsageReportDownloadURL, see UsageReportDownloadURL Schema.
UsageReportScheduleEntity, see UsageReportScheduleEntity Schema.
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
}
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
}
See also: SubscriptionEntity Schema
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
}
See also: TenantAdminUserEntity Schema
See also: SubscriptionEntity Schema
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
}
See also: TenantEntity Schema
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
}
See also: DeleteErrorReportEntity Schema
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, see Adding a Tenant.
Retrieving all tenants, see Retrieving a list of Tenants.
Requesting an increase to the maximum tenant cap, see Creating a Request to Increase the Tenant Limit.
Updating a tenant’s details, see Editing a Tenant Configuration.
Generating a new usage summary report, see Generating a new usage summary report.
Retrieving the list of usage summary reports, see Retrieving the list of Usage Reports.
Deleting a usage summary report, see Deleting a list of Usage Reports.
Obtaining the URL to download a usage summary report, see Obtaining the URL to Download a Usage Report.
Creating a new usage summary report schedule, see Creating a Usage Summary Report Schedule.
Retrieving the usage summary report schedule, see Retrieving the Usage Report Schedule.
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"
}
]
}
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:
Method: POST /api/msp/reports/usage/schedule
Resource: Path
JSON Data: JSON dictionary representing a new UsageReportScheduleEntity Schema entity.
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
}