API Overview

Before a 3rd Party Application can access the NetSapiens API, it must obtain an access token via the OAuth2 standard.

API Base UrL URL

As reseller of Skyswitch, you should use the Portal & API node assigned to your account. There are two ways you can access the Portal & API.

Using your Reseller ID

If your Reseller ID is 12345, Skyswitch's Manager portal is available at https://12345-hpbx.dashmanager.com.

Your API base URL will be https://12345-hpbx.dashmanager.com/ns-api/.

Using your Branded Domain

If your Branded Manager portal is at https://portal.acmecorp.com, your API base URL will be https://portal.acmecorp.com/ns-api/.

Access Token Privileges

The username and password used to access the api can be any valid Subscriber username and password that can log into the Manager portals. The scope of the Subscriber will determine what access your token will be granted.

Scope	Access Level
Basic User	Read and Modify any data related to the Subscriber
Office Manager	Read and Modify any data related to the Subscriber's Domain
Reseller	Read and Modify any data related to any domain under the same Reseller

Client ID and Client Secret

A Client ID and Secret along with the username and password of a Subscriber will be required to retrieve an access token. Please request a Client ID and Secret from Support if you currently do not have a Client ID and Secret.

curl https://12345-hpbx.dashmanager.com/ns-api/oauth2/token/ \
-dclient_id=your-client-id \
-dclient_secret=your-client-secret \
-dusername=111@abc-company \
-dpassword=1234 \
-dgrant_type=password

{  
  "access_token":"90679e87dc2e6409211e822434122aaf9480",
  "expires_in":3600,
  "scope":"Reseller",
  "token_type":"Bearer",
  "refresh_token":"c7bf58a0247e02efc6ee4340f01ed629",
  "legacy": false,
  "domain": "abc-company.12345.service",
  "apiversion": "Version: 41.1.0"
}

📘
Multi-Factor Authentication
If the Subscriber you in use has Multi-Factor Authentication enabled there is an additional authentication step required when accessing the token. Below is a snippet example of the response and new request when MFA is enabled.

{
  "mfa":"mfa_required",
  "mfa_vendor":"google",
  "mfa_type":"authenticator",
  "access_token":"51fdab21ca330f6b0c88b2a98ex8932s"
  ,"expires_in":3600
  ,"token_type":"Bearer"
  ,"refresh_token":"08da6c024e9b90eafafcfsdf3c5d449"
  ,"client_id":"your-client-id"
}

Use the mfa_vendor, mfa_type, and access_token from the response to send the request again with the Authenticator Password. You do not need to send the username or password again.

curl https://12345-hpbx.dashmanager.com/ns-api/oauth2/token/ \
-dclient_id=your-client-id \
-dclient_secret=your-client-secret \
-dns_id_type=subscriber \
-dmfa-type=authenticator \
-dmfa_vendor=google \
-daccess_token=51fdab21ca330f6b0c88b2a98ex8932s \
-dpasscode=246802 \
-dgrant_type=mfa

After the second request, you will then get a response with a new access token.

{  
  "access_token":"90679e87dc2e6409211e822434122aaf9480",
  "expires_in":3600,
  "scope":"Reseller",
  "token_type":"Bearer",
  "refresh_token":"c7bf58a0247e02efc6ee4340f01ed629",
  "legacy": false,
  "domain": "abc-company.12345.service",
  "apiversion": "Version: 41.1.0"
}

Using the Access Token

Once an Access Token is acquired, each additional request needs to contain this token in the Authorization header as follows:

Authorization: Bearer 90679e87dc2e6409211e822434122aaf9480

Refreshing a Token

An expiring token can be refreshed to get a new access token without the need for the username and password to be resubmitted.

curl --location --request GET 'https://12345-hpbx.dashmanager.com/ns-api/oauth2/token/?grant_type=refresh_token&client_id=your-client-id&client_secret=your-client-secret&refresh_token=c7bf58a0247e02efc6ee4340f01ed629'

{
    "access_token": "3b9d3229d70b442e99e0dfa050473d63",
    "expires_in": 3600,
    "scope": "Reseller",
    "token_type": "Bearer",
    "refresh_token": "c7bf58a0247e02efc6ee4340f01ed629",
    "legacy": false,
    "domain": "abc-company.12345.service",
    "apiversion": "Version: 41.1.0"
}

Use the new token in the Authorization header of succeeding requests.

Authorization: Bearer 3b9d3229d70b442e99e0dfa050473d63

Inspecting an Access Token

An access token can be expected to learn more information about the token. It can be used to retrieve the territory (Reseller ID), domain and the expiration among other information.

curl --location --request GET 'https://12345-hpbx.dashmanager.com/ns-api/oauth2/read?format=json' \
--header 'Authorization: Bearer 3b9d3229d70b442e99e0dfa050473d63'

{
    "token": "3b9d3229d70b442e99e0dfa050473d63",
    "client_id": "your-client-id",
    "territory": "12345",
    "domain": "abc-company.12345.service",
    "uid": "111@abc-company.12345.service",
    "expires": "2020-06-11 21:04:14",
    "scope": "Reseller",
    "apiversion": "Version: 41.1.0"
}

Masquerading

A higher-scoped user may masquerade as a lower-scoped user. Masquerading entails a higher-scoped user to get a token of a lower-scoped user without the need to use the latter’s password. As a specific example, a Reseller user token may get a token on behalf of a Basic User. The returned Basic User’s access_token can then be used as if it's the Basic User making the API calls.

First, get token of the higher scoped user, say a Reseller.

curl --location --request POST 'https://12345-hpbx.dashmanager.com/ns-api/oauth2/token/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=your-client-id' \
--data-urlencode 'client_secret=your-client-secret' \
--data-urlencode 'username=1000@acmercorp.12345.service' \
--data-urlencode 'password=mypassword'

{
    "username": "reseller@acmercorp",
    "user": "1000",
    "territory": "12345",
    "domain": "acmecorp.12345.service",
    "uid": "1000@acmecorp.12345.service",
    "scope": "Reseller",
    "user_email": "",
    "displayName": "Reseller ABC",
    "access_token": "1e465ded5f3b4536aa71313b239a8162",
    "expires_in": 3600,
    "token_type": "Bearer",
    "refresh_token": "91ab3f03cfcc3f020fa8c37340b80b9a",
    "client_id": "redacted",
    "apiversion": "Version: 41.1.0"
}

Then use the Reseller's access_token above as the access_token param in next API call.

📘
The mask_uid specifies the lower-scoped user to be masqueraded. It is always in <extension number>@<full domain string> form.

curl --location -g --request POST '<https://12345-hpbx.dashmanager.com/ns-api/oauth2/token/>'  
--header 'Content-Type: application/x-www-form-urlencoded'  
--data-urlencode 'grant_type=masquerade'  
--data-urlencode 'client_id=your-client-id'  
--data-urlencode 'client_secret=your-client-secret'  
--data-urlencode 'mask_uid=5000@acmecorp.12345.service'  
--data-urlencode 'access_token=1e465ded5f3b4536aa71313b239a8162'

{
    "territory": "12345",
    "domain": "acmecorp.12345.service",
    "scope": "Basic User",
    "uid": "5000@acmecorp.12345.service",
    "access_token": "1357f6c97f418fc0289fc67507205668",
    "expires_in": 3600,
    "token_type": "Bearer",
    "refresh_token": "f9fe0e833c674d023e076d524e714260",
    "client_id": "teams.client",
    "apiversion": "your-client-id"
}

Note above that the result shows a new access_token for a user with userid equivalent to the passed mask_uid and it has a lower scope (Basic User).