API

About Harmony SASE

Harmony SASE provides secure access to local networks, applications and cloud infrastructures with one unified platform. By transforming the outdated, hardware-based security appliances into a cloud-based SaaS solution, we are simplifying network security for the modern and distributed workforce and helping organizations of all sizes and in many industries to secure their remote workers.

Classes

The main path classes are Users, Groups, Addons, and Networks.

• Users, also known as members, belong to Groups.
• Groups consist of applications, networks, VPN locations, and users.
• Addons consist of license and billing information for members and gateways, and form the basis of a Subscription.
• Networks hold information, such as geographic location, regions, health status, and details about instances and regional identity providers.

See Schemas below.

Getting Started

In order to access the Harmony SASE API, the user must belong to either the Premium Plus or Enterprise plan. If the user does not belong to one of the plans, in the workspace Settings page, the message ‘Your current plan doesn’t include API Support’ will appear under API Support.

Authentication and Authorization

The Swagger Editor (https://editor.swagger.io) is the gateway for the actual API environment.

Harmony SASE uses two-step secure tokens for authentication. The first token, known as the API key, is used to generate the second token, a time-based access token.

Following are instructions for generating the tokens.

1. In the web client API Support page, select Generate New Token.
2. In the Generate New Token dialog box, enter the name of the token in the Name box.
3. In the Expiration Date list, select an expiration date or the default ‘Never’.
4. In the Define token section, select the needed permissions, such as ‘View list of users’, ‘Add a new member’, and ‘Delete’, in the list.
5. Select Generate to create the first token.
6. At the top of the API Support page, the ‘Token was generated successfully. Copied to clipboard’ message will appear. In the Active Tokens list, you can see the new token.
7. Generate the access token with a call to the POST /v1/auth/authorize endpoint, described below.
8. In the Swagger UI, select Authorize.
9. In the Authorize prompt, paste the access token generated by the API call.

The time-based access token is generated. Now you can use any of the APIs in the Swagger environment within the time limit of the access token.

Following is the Authorize call:

POST /v1/auth/authorize

Parameters: None

Request Body:

Request Example:

curl -X ‘POST’ \  ‘https://api.perimeter81.biz/api/rest/v1/auth/authorize’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \  -d ‘{      "grantType": "api_key",      "apiKey": "[KEY-FROM-GENERATE]"}’

Response:

Response Body:

Response Example:

{    "data": {          "tokenType": "bearer",          "accessToken": "[THE_ACCESS_TOKEN]",          "accessTokenExpire": [TIMESTAMP]     }}

Now you can use the APIs for external calls during the next hour.

Base URI

The base URI to the API is https://api.perimeter81.biz/api/rest.

Media Type

The media type for all requests is application/json for all requests.

Basic Workflow

The basic workflow consists of:

1. Add users (members) using POST /v1/users.
2. Create groups using POST /v1/groups.
3. Add members to groups using POST /v1/groups/{groupId}/member/{userId}.
4. Add licenses for members and gateways using POST /v1/addons/members and POST /v1/addons/gateways.
5. Check the health of the networks using GET /v1/networks/{id}.
6. Use the GET and DELETE methods to manage the Users and Groups resources.

Users

The Users methods manage the Users resource. Users belong to Groups.

POST /v1/users

Create a new user.

Parameters: None

Request Body: CreateUserDto

Request Example:

curl -X ‘POST’ \  ‘https://api.perimeter81.biz/api/rest/v1/users’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \  -d ‘{            "idpType": "database",             "accessGroups": [ "string" ],             "email": "string",             "emailVerified": true,             "inviteMessage": "string",             "profileData": {                 "firstName": "string",                 "lastName": "string",                 "roleName": "string",                 "phone": "string",                 "icon": "string"         },         "origin": "string" }’

Response:

Response Example:

{     "terminated": true,     "email": "string",     "emailVerified": true,     "initials": "string",     "roleName": "string",     "lastName": "string",     "firstName": "string",     "username": "string",     "id": "string" } 

GET /v1/users

Get a paginated list of users.

Parameters:

Request Body: None

Request Example:

curl – X ‘GET’ \  ‘https://api.perimeter81.biz/api/rest/v1/users/?page=2&limit=25&q=Ace&qType=full’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \

Response:

Response Example:

{      "data": [      {         "terminated": true,         "email": "string",         "emailVerified": true,         "initials": "string",         "roleName": "string",         "lastName": "string",         "firstName": "string",         "username": "string",         "id": "string"         }     ],     "page": 1,     "totalPage": 1,     "itemsTotal": 10 }

DELETE /v1/users/{id}

Delete a user.

Parameters:

Request Body: None

Request Example:

curl – X ‘DELETE’ \  ‘https://api.perimeter81.biz/api/rest/v1/users/?id=47438’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \

Response:

Response Example:

{    "terminated": true,    "email": "string",     "emailVerified": true,     "initials": "string",     “rolename”: “string”,    "lastName": "string",        "firstName": "string",     "username": "string",    "id": "string" }

Groups

Groups contain applications, networks, VPN locations, and members (users) that have access to resources.

POST /v1/groups

Create an access group which holds applications, networks, VPN locations, and users.

Parameters: None

Request Body: CreateGroupDto

Request Example:

curl -x ‘POST’ \  ‘https://api.perimeter81.biz/api/rest/v1/groups/?groupId=43533&userId=981347’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \  -d ‘{  “name”; “string”,  “description: “string”}’

Response:

Response Example:

{     "name": "string",     "isDefault": true,     "applications": [         "string"     ],    "networks": [         "string"    ],     "vpnLocations": [         "string"     ],     "users": [         "string"     ],     "id": "string" }

GET /v1/groups

Get a paginated list of groups.

Parameters:

Request Body: None

Request Example:

curl – X ‘GET’ \  ‘https://api.perimeter81.biz/api/rest/v1/groups/?page=2&limit=25&sort[field]=asc’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \

Response:

Response Example:

{     "data": [         {             "name": "string",             "isDefault": true,             "applications": [                "string"             ],             "networks": [                "string"             ],             "vpnLocations": [                "string"             ],             "users": [                "string"             ],             "id": "string"         }     ],     "page": 1,     "totalPage": 1,     "itemsTotal": 10 }

DELETE /v1/groups/{id}

Delete a group by ID.

Parameters:

Request Body: None

Request Example:

curl – X ‘DELETE’ \  ‘https://api.perimeter81.biz/api/rest/v1/groups/?id=4732276’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \

Response:

Response Example:

{     "name": "string",     "isDefault": true,     "applications": [         "string"     ],     "networks": [         "string"     ],     "vpnLocations": [         "string"     ],     "users": [         "string"     ],    "id": "string" }

POST /v1/groups/{groupId}/member/{userId}

Add a member to a group.

Parameters:

Request Body: None

Request Example:

curl – X ‘POST’ \  ‘https://api.perimeter81.biz/api/rest/v1/groups/?groupId=43533/member/?userId=981347’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \

Response:

Response Example:

{     "name": "string",     "isDefault": true,     "applications": [         "string"     ],     "networks": [         "string"     ],     "vpnLocations": [         "string"     ],     "users": [         "string"     ],    "id": "string" }

DELETE /v1/groups/{groupId}/member/{userId}

Delete a member from a group.

Parameters:

Request Body: None

Request Example:

curl – X ‘DELETE’ \  ‘https://api.perimeter81.biz/api/rest/v1/groups/?groupId=G732276/member/?userId=4743568’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \

Response:

Response Example:

{     "name": "string",     "isDefault": true,     "applications": [         "string"     ],     "networks": [         "string"     ],     "vpnLocations": [         "string"     ],     "users": [         "string"     ],    "id": "string" }

Addons

Each addon is a purchased license for a member (users) or a gateway.

GET /v1/addons

Get a list of addons.

Parameters: None

Request Body: None

Request Example:

curl – X ‘GET’ \  ‘https://api.perimeter81.biz/api/rest/v1/addons’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \

Response:

Response Example:

{     "data": [        {            "remaining": 0,            "expired": 0,            "total": 0,            "additionalType": "string",            "used": 0        }    ] }

POST /v1/addons/members

Add the number of purchased licenses for members.

Parameters: None

Request Body: BuyAddonsDto

Request Example:

curl – X ‘POST’ \  ‘https://api.perimeter81.biz/api/rest/v1/addons/members’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \  -d ‘{  “amount”: 1}’

Response:

Response Example:

{     "addons": [       {             "amount": 0,             "quantity": 0,             "additionalType": "string",             "currencyCode": "string",             "pricingModel": "string",             "periodUnit": "string",             "status": "string",             "price": 0,             "id": "string"         }     ],     "currencyCode": "string",     "deleted": true,     "status": "string",     "billingPeriodUnit": "string",     "id": "string"}

POST /v1/addons/gateways

Add the number of purchased gateway licenses.

Parameters: None

Request Body: BuyAddonsDto

Request Example:

curl – X ‘POST’ \  ‘https://api.perimeter81.biz/api/rest/v1/addons/gateways’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \  -d ‘{  “amount”: 1}’

Response:

Response Example:

{     "addons": [       {             "amount": 0,             "quantity": 0,             "additionalType": "string",             "currencyCode": "string",             "pricingModel": "string",             "periodUnit": "string",             "status": "string",             "price": 0,             "id": "string"         }     ],     "currencyCode": "string",     "deleted": true,     "status": "string",     "billingPeriodUnit": "string",     "id": "string"}

Networks

View network resources.

GET /v1/networks

Get list of networks.

Parameters: None

Request Body: None

Request Example:

curl – X ‘GET’ \  ‘https://api.perimeter81.biz/api/rest/v1/networks’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \

Response:

Response Example:

{     "data": [         {              "geoPoint": {                  "__type": "string",                 "latitude": 0,                 "longitude": 0 },                 "name": "string",                 "isDefault": true,                 "regions": [                     {                         "geoPoint": {                            "__type": "string",                            "latitude": 0,                            "longitude": 0                         },                        "name": "string",                        "instances": [                          {                              "tunnels": "string",                              "id": "string"                          }                       ],                       "provider": {                           "region": "string",                           "continentCode": "string",                           "countryCode": "string"                       },                       "id": "string"                   }              ],               "id": "string"          }     ] }

GET /v1/networks/{id}

Get the health status of a network.

Parameters:

Request Body: None

Request Example:

curl – X ‘GET’ \  ‘https://api.perimeter81.biz/api/rest/v1/networks/?id=4732276437’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \

Response:

Response Example:

{     "health": [         {             "type": "string",             "meta": {                 "networkId": "string",                 "instanceId": "string"             },            "status": true        }     ] }

Schemas

Addon

Information for a single addon. Found in Subscription.

AddonStatistics

Statistics for a single addon. Found in AddonsStatisticsList.

AddonsStatisticsList

List of statistics for all addons. Response to GET /v1/addons.

BuyAddonsDto

DTO for purchasing addons. Request body in POST /v1/addons/members and POST /v1/addons/gateways.

CreateGroupDto

DTO for creating a group. Request body in POST /v1/groups.

CreateUserDto

DTO for creating a user. Request body in POST /v1/users.

Group

Data for a single group. Response to POST /v1/groups, DELETE /v1/groups/{id}, POST /v1/groups/{groupId}/member/{userId}, and DELETE /v1/groups/{groupId}/member/{userId}. Found in GroupList.

GroupList

List of Group. Response to GET /v1/groups.

Network

Network information. Found in NetworkList.

NetworkGeoPoint

Geographical point information. Found in Network and NetworkRegion.

NetworkHealth

Health status of network health. Response to GET /v1/networks/{id}.

NetworkInstance

A network instance. Found in NetworkRegion.

NetworkList

List of networks. Response to GET /v1/networks.

NetworkMeta

Metadata for a network. Found in NetworkStatus.

NetworkProvider

Provider of the network. Found in NetworkRegion.

NetworkRegion

Network region. Found in Network.

NetworkStatus

Status of an individual network. Found in NetworkHealth.

PaginatedList

Object for a paginated list.

PaginationQueryDto

DTO for query about pagination options.

ProfileSchema

Profile information. Found in CreateUserDto.

SearchQueryDto

DTO for query of search options.

SortQueryDto

DTO for query of sort options.

Subscription

List of subscription addons. Response to POST /v1/addons/members and POST /v1/addons/gateways.

User

A user, also known as a member. Response to POST /v1/users and DELETE /v1/users/{id}. Found in UserList.

UserList

List of users. Response to GET /v1/users.

UserProfileDto

DTO for user profile. Found in CreateUserDto.

Enumerations

idpType

Type of the identity provider. Found in CreateUserDto.

qOperator

Search operation only applicable if qType equals ‘partial’. Found in SearchQueryDto.

qType

Type of search. Found in SearchQueryDto.