API

30 Jan 2024
10 Minutes to read
Contributors

API

Updated on 30 Jan 2024
10 Minutes to read
Contributors

Article summary

Did you find this summary helpful?

Thank you for your feedback

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, 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 Settings page, the message ‘Your current plan doesn’t include API Support’ will appear under API Support.

Authentication and Authorization

Note

You may use the Swagger Editor (https://editor.swagger.io) as the gateway for the actual API environment and send different API requests to the platform.

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.

In the web client API Support page, select Generate New Token.
In the Generate New Token dialog box, enter the name of the token in the Name box.
In the Expiration Date list, select an expiration date or the default ‘Never’.
In the Define token section, select the needed permissions, such as ‘View list of users’, ‘Add a new member’, and ‘Delete’, in the list.
Select Generate to create the first token.
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.
Generate the access token with a call to the POST /v1/auth/authorize endpoint, described below.
In the Swagger UI, select Authorize.
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

Each access token expires at the end of 1 hour.

Parameters: None

Request Body:

Property	Data Type	Description
grantType	String	Authorize request type: 'api_key'.
apiKey	String	API key from Generate New Token in the web client.

Request Example:

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

Response:

Status Code	Message/JSON Response Body	Description
200	See Response Body table below.	Success. Access token and expiration time returned.

Response Body:

Property	Data Type	Description
data	Object	Return object with access token and its expiration timestamp.
token	String	Type of token. Value is ‘bearer’.
accessToken	String	Access token. Expires according to accessTokenExpire.
accessTokenExpire	String	Timestamp of access token’s expiration.

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.com/api/rest.

Media Type

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

Basic Workflow

The basic workflow consists of:

Add users (members) using POST /v1/users.
Create groups using POST /v1/groups.
Add members to groups using POST /v1/groups/{groupId}/member/{userId}.
Add licenses for members and gateways using POST /v1/addons/members and POST /v1/addons/gateways.
Check the health of the networks using GET /v1/networks/{id}.
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.com/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:

Status Code	Message/Response Body	Description
201	User	Success. Resource is created.
400		Bad request.

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:

Property	Data Type	Description
page	Integer	Page to start from.
limit	Integer	The number of records per page.
q	String	Search string or URL encoded JSON.
qType	String	Type of search. One of: full [default] partial
qOperator	String	Applicable only if qType is set to 'partial'. One of: and or [default]
sort	Object	Map of fields and sort order. { "field1": "asc", "field2": "desc" } Example: ?sort[field1]=asc&sort[field2]=desc

Request Body: None

Request Example:

curl -X GET -H 'Authorization: Bearer <ACCESS_TOKEN>' / 
-H 'Content-Type: application/json' 'https://api.perimeter81.com/api/rest/v1/users?page=1&qType=partial'

Response:

Status Code	Message/Response Body	Description
200	UserList	Success. List of users is returned.

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:

Property	Data Type	Description
id*	String	ID of user to delete.

Request Body: None

Request Example:

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

Response:

Status Code	Message/Response Body	Description
200	User	Success. User deleted.
404		Not found.

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.com/api/rest/v1/groups/?groupId=43533&userId=981347'  -H 'accept: application/json'  -H 'Content-Type: application/json'  -d '{  “name”; “string”,  “description: “string”}'

Response:

Status Code	Message/Response Body	Description
201	Group	Success. Group created.

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:

Property	Data Type	Description
page	Integer	Page to start from.
limit	Integer	Number of records per page.
sort	Object	Map of fields and sort order. Example: ?sort[field1]=asc&sort[field2]=desc.

Request Body: None

Request Example:

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

Response:

Status Code	Message/Response Body	Description
200	GroupList	Success. List returned.

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:

Property	Data Type	Description
id*	String	ID of group to delete.

Request Body: None

Request Example:

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

Response:

Status Code	Message/Response Body	Description
200	Group	Success. Group deleted.

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:

Property	Data Type	Description
groupId*	String	ID of group.
userId*	String	ID of user.

Request Body: None

Request Example:

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

Response:

Status Code	Message/Response Body	Description
201	Group	Success. Group member added.

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:

Property	Data Type	Description
groupid*	String	ID of group that member belongs to.
userid*	String	ID of member to delete from the group.

Request Body: None

Request Example:

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

Response:

Status Code	Message/Response Body	Description
200	Group	Success. Member removed from group.

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.com/api/rest/v1/addons' -H 'accept: application/json'  -H 'Content-Type: application/json'

Response:

Status Code	Message/Response Body	Description
200	AddonsStatisticsList	Success. List of addons returned.

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.com/api/rest/v1/addons/members'   -H 'accept: application/json'   -H 'Content-Type: application/json'   -d '{  “amount”: 1}'

Response:

Status Code	Message/Response Body	Description
200	Subscription	Success. Subscription object with a list of addons returned.

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.com/api/rest/v1/addons/gateways'  -H 'accept: application/json'   -H 'Content-Type: application/json'   -d '{  “amount”: 1}'

Response:

Status Code	Message/Response Body	Description
200	Subscription	Success. Subscription object with a list of addons returned.

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.com/api/rest/v1/networks’ \  -H ‘accept: application/json’ \  -H ‘Content-Type: application/json’ \

Response:

Status Code	Message/Response Body	Description
200	NetworkList	Success. List of networks returned.

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:

Property	Data Type	Description
id*	String	ID of network.

Request Body: None

Request Example:

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

Response:

Status Code	Message/Response Body	Description
200	NetworkHealth	Health of network.

Response Example:

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

Schemas

Addon

Information for a single addon. Found in Subscription.

Property	Data Type	Description
amount*	Number	Number of new addons to purchase.
quantity*	Number	Total number of addons.
additionalType	String	Internal name of addon.
currencyCode	String	ISO currency code. Currently, only 'USD'.
pricingModel	String	Addon pricing model. One of: volume per_unit flat_fee
periodUnit*	String	Payment period. One of: month year
status	String	Addon status. Value 'active'.
price*	Number	Price of addon.
id*	String	ID of addon.

AddonStatistics

Statistics for a single addon. Found in AddonsStatisticsList.

Property	Data Type	Description
remaining*	Number	Number of addons remaining.
expired*	Number	Number of addons that expired.
total*	Number	Total number of addons.
additionalType*	String	Internal name of addon.
used*	Number	Number of addons used.

AddonsStatisticsList

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

Property	Data Type	Description
data*	Array of AddonStatistics	List of addon statistics.

BuyAddonsDto

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

Property	Data Type	Description
amount*	Integer	Number of addons to purchase. Minimum 1.

CreateGroupDto

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

Property	Data Type	Description
name	String	Name of group.
description	String	Description of group.

CreateUserDto

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

Property	Data Type	Description
idpType	String	Type of identity provider. One of: database saml gsuite okta azureAD adLdap See idpType.
accessGroups	Array of String	List of access Groups to which user belongs.
email*	String ($UTF8)	User’s email address.
emailVerified	Boolean	Whether email is verified (true).
inviteMessage*	String	Invitation message.
profileData	ProfileSchema	Profile information.
origin	String ($UTF8)	Source. Minimum length of 1.

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.

Property	Data Type	Description
name*	String	Name of group.
isDefault*	Boolean	Whether group is the default (true).
applications*	Array of String	List of group applications.
networks*	Array of String	List of group networks.
vpnLocations*	Array of String	List of group VPN locations.
users*	Array of String	List of group members.
id*	String	Group ID.

GroupList

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

Property	Data Type	Description
data*	Array of Group	List of groups.
page*	Number	Page number.
totalPage*	Number	Number of pages in list.
itemsTotal*	Number	Number of items in list.

Network

Network information. Found in NetworkList.

Property	Data Type	Description
geoPoint*	NetworkGeoPoint	Network geographical point information.
name*	String	Name of network.
isDefault*	Boolean	Whether network is the default (true).
regions*	Array of NetworkRegion	List of network regions.
id*	String	ID of network.

NetworkGeoPoint

Geographical point information. Found in Network and NetworkRegion.

Property	Data Type	Description
__type*	String	Geo point type. Private.
latitude*	Number	Geo point latitude.
longitude*	Number	Geo point longitude.

NetworkHealth

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

Property	Data Type	Description
health*	Array of NetworkStatus	List of network statuses.

NetworkInstance

A network instance. Found in NetworkRegion.

Property	Data Type	Description
tunnels*	String	Tunnels.
id*	String	ID of instance.

NetworkList

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

Propeerty	Data Type	Description
data*	Array of Network	List of networks.

NetworkMeta

Metadata for a network. Found in NetworkStatus.

Property	Data Type	Description
networkId*	String	ID of network.
instanceId*	String	ID of instance.

NetworkProvider

Provider of the network. Found in NetworkRegion.

Property	Data Type	Description
region*	String	Provider region.
continentCode*	String	Provider continent code.
countryCode*	String	Provider country code.

NetworkRegion

Network region. Found in Network.

Property	Data Type	Description
geoPoint*	NetworkGeoPoint	Network's geographical points.
name*	String	Name of region.
instances*	Array of NetworkInstance	List of network instances.
provider*	NetworkProvider	Network provider.
id*	String	ID of region.

NetworkStatus

Status of an individual network. Found in NetworkHealth.

Property	Data Type	Description
type*	String	Network type. Currently, only 'gateway'.
meta*	NetworkMeta	Metadata for a network.
status*	Boolean	Whether network is active (true).

PaginatedList

Object for a paginated list.

Property	Data Type	Description
page*	Number	Page number.
totalPage*	Number	Number of pages in list.
itemsTotal*	Number	Number of items in list.

PaginationQueryDto

DTO for query about pagination options.

Property	Data Type	Description
page	Integer	Page to start from. Minimum 1.
limit	Integer	Number of records per page. Maximum 100.

ProfileSchema

Profile information. Found in CreateUserDto.

Property	Data Type	Description
firstName	String	First name of user.
lastName	String	Last name of user.
roleName	String	Name of user's role.
phone	String	Telephone.
icon	String	User's icon, if any.

SearchQueryDto

DTO for query of search options.

Property	Data Type	Description
q	String	Search string or URL encoded JSON.
qType	String	Type of search. One of: full [default] partial
qOperator	String	Applicable only if qType equals 'partial'. One of: and or [default]

SortQueryDto

DTO for query of sort options.

Property	Data Type	Description
sort	String	Map of fields and sort order. Example: ?sort=[field1]=asc&sort[field2]=desc

Subscription

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

Property	Data Type	Description
addons*	Array of Addon	List of subscription addons.
currencyCode*	String	ISO currency code. Currently, only 'USD'.
deleted*	Boolean	Whether subscription is deleted (true).
status*	String	Status of subscription. One of: non_renewing active
billingPeriodUnit*	String	Unit of billing period. Currently, only '1'.
id*	String	ID of subscription.

User

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

Property	Data Type	Description
terminated*	Boolean	Whether user is deleted (true).
email*	String ($UTF8)	User email.
emailVerified*	Boolean	Whether email is verified (true).
initials*	String	User initials.
roleName*	String	User role.
lastName*	String	User last name.
firstname*	String	User first name.
id*	String	ID of user.

UserList

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

Property	Data Type	Description
data*	Array of User	List of users.
page*	Number	Number of page.
totalPage*	Number	Number of pages in list.
itemsTotal*	Number	Number of items in list.

UserProfileDto

DTO for user profile. Found in CreateUserDto.

Property	Data Type	Description
firstName	String	Pattern: ^[a-z ‘-]+$ maxLength: 30
lastName	String	Pattern: ^[a-z ‘-]+$ maxLength: 30
roleName	String	Name of role.
phone	String	Pattern: ^[+] {0,1} [0-9] {11,15} $ maxLength: 30
icon	String	User icon.

Enumerations

idpType

Type of the identity provider. Found in CreateUserDto.

Value	Description
database	Database-based authentication.
saml	Security Assertion Markup Language standard for authentication and authorization.
gsuite	Google Workspace cloud tool.
okta	Okta identity and access management.
azureAD	Microsoft Azure Active Directory authentication.
adLdap	PHP class that provides LDAP authentication and integration with Active Directory.

qOperator

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

Value	Description
and	Boolean operator for all values required.
or	Boolean operator for at least one value is required [default].

qType

Type of search. Found in SearchQueryDto.

Value	Description
full	Full search [default]
partial	Partial search. Partial search query can include qOperator.

Was this article helpful?

What's Next

Table of contents

About Harmony SASE
Classes
Getting Started
Users
Groups
Addons
Networks
Schemas
Enumerations