InControl 2 API

The InControl 2 API opens up a world of possibilities for integrating our platform with your custom apps, web site, or other third party software.


Please review the following Peplink InControl API License Agreement And Terms Of Use

PEPLINK INCONTROL API LICENSE AGREEMENT

AND

TERMS OF USE


Overview of the Peplink InControl API Package and License Grant. The Peplink InControl API Package consists of a package or suite of different applications programmer's interfaces (hereinafter referred to for convenience as "the API" whether You access one or multiple interfaces) that will allow your application to directly interface with Peplink/Pepwave devices and/or Peplink web services. Subject to the terms and restrictions set forth in these Terms of Use, Peplink grants You a limited, non-exclusive, non-transferable and non-sublicensable license for the sole purpose of embedding the API and underlying content into your application so that your application can interface directly with Peplink/Pepwave devices and/or Peplink InControl web services. In order to use and access the API, You must register for an API account ("Account") with Peplink.

Updates and Modifications. Peplink may, at its sole discretion, release subsequent versions of the API and underlying data and require You to obtain and use the most current version. In addition, Peplink may modify these Terms of Use at any time with or without notice. If a subsequent version is unacceptable to You, You may cancel the API at any time by simply deleting the API from Your application. If You continue to use the API on Your application, You will be deemed to have accepted any modifications.

Restrictions on Use.
You have no rights with respect to the API or any portion thereof and shall not use the API or any portion thereof except as expressly set forth herein. Without limiting the generality of the foregoing, You agree not to (i) modify or create derivative works of the API; (ii) sublicense, lease, rent, assign, distribute, repackage, rebrand, or otherwise transfer or disclose the API, any portion thereof or any documentation to any third party; (iii) use the API on or in connection with any application other than Peplink InControl; or (iv) cause, assist or permit any third party (including an end-user) to do any of the foregoing.

Specifically excluded from the license set forth in these Terms of Use are any uses or operation of the API in connection with any products, web services, software, web sites, systems, applications or hardware other than Peplink InControl or devices manufactured by Peplink/Pepwave or any of its subsidiaries.

You agree to be fully responsible for your own conduct and content while using the API, and for any consequences thereof. You agree to use the API only for purposes that are legal, proper and in accordance with these Terms of Use and any applicable policies or guidelines. By way of example, and not as a limitation, You agree that when using the API, You will not:

upload, post, email or transmit or otherwise make available any Content that infringes any patent, trademark, copyright, trade secret or other proprietary right of any party, unless You are the owner of the Rights or have the permission of the owner to post such Content;
use the API for any illegal or unauthorized purpose;
remove or alter any copyright, trademark or other proprietary rights notices contained in the API or any other Peplink content, including but not limited to maps and/or driving directions;
submit content that falsely expresses or implies that such content is sponsored or endorsed by Peplink; or
transmit any viruses, worms, defects, Trojan horses, or any items of a destructive nature.

Termination of Use. Peplink hereby reserves all rights to discontinue Your access to the API and the underlying content at any time, at Peplink's sole discretion, for any reason, with or without notice.

DISCLAIMER OF WARRANTIES
YOUR USE OF THE API IS AT YOUR SOLE RISK. THE API IS PROVIDED ON AN "AS IS" AND "AS AVAILABLE" BASIS. PEPLINK EXPRESSLY DISCLAIMS ALL WARRANTIES OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.

PEPLINK MAKES NO WARRANTY THAT (i) THE API WILL MEET YOUR REQUIREMENTS, (ii) THE API WILL BE UNINTERRUPTED, TIMELY, SECURE, OR ERROR-FREE, AND/OR THAT (iii) ANY ERRORS IN THE SOFTWARE WILL BE CORRECTED.

ANY MATERIAL DOWNLOADED OR OTHERWISE OBTAINED THROUGH THE API IS DONE AT YOUR OWN DISCRETION AND RISK AND. YOU WILL BE SOLELY RESPONSIBLE FOR ANY DAMAGE TO YOUR COMPUTER SYSTEM/NETWORK OR ANY LOSS OF DATA THAT MAY RESULT FROM THE DOWNLOAD OF ANY SUCH MATERIAL OR THE USE OF THE API.


LIMITATION OF LIABILITY
YOU EXPRESSLY UNDERSTAND AND AGREE THAT IN NO EVENT Peplink SHALL BE LIABLE TO YOU FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR ANY OTHER DAMAGES, INCLUDING BUT NOT LIMITED TO, DAMAGES FOR LOSS OF PROFITS, GOODWILL, USE, DATA OR OTHER INTANGIBLE LOSSES (EVEN IF PEPLINK HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES), RESULTING FROM: (i) THE USE OR THE INABILITY TO USE THE API; (ii) UNAUTHORIZED ACCESS TO OR ALTERATION OF YOUR TRANSMISSIONS OR DATA; OR (iii) ANY OTHER MATTER RELATING TO THE API. Some jurisdictions do not allow the exclusion of certain warranties or the limitation or exclusion of liability for incidental or consequential damages. Accordingly, some of the above limitations of clauses 7 and 8 may not apply to you.

INDEMNIFICATION
You agree to indemnify and hold harmless Peplink, and its subsidiaries, affiliates, officers, agents, and employees, advertisers, licensors, and partners, from and against any third party claim arising from or in any way related to your use of the API, violation of these Terms of Use or any other actions connected with use of any Peplink Applications, including any liability or expense arising from all claims, losses, damages (actual and consequential), suits, judgments, litigation costs and attorneys' fees, of every kind and nature. In such a case, Peplink will provide You with written notice of such claim, suit or action.

INTELLECTUAL PROPERTY RIGHTS
"Intellectual Property Rights" shall mean any and all rights existing under patent law, copyright law, semiconductor chip protection law, moral rights law, trade secret law, trademark law, unfair competition law, publicity rights law, privacy rights law, and any and all other proprietary rights, and any and all applications, renewals, extensions and restorations thereof, now or hereafter in force and effect worldwide. As between You and Peplink, You acknowledge that Peplink owns all right, title and interest, including without limitation all Intellectual Property Rights, in and to the API, including but not limited to the API and any mapping data accessed by virtue of the API, and that You shall not acquire any right, title, or interest in or to the API, except the limited license expressly set forth in the Terms of Use. You agree that You shall not disclose anything related, directly or indirectly, about the API to any third parties. You further acknowledge that You will only disclose the API to your colleagues on "need-to-know" basis.

Trademark License. For purposes of the Terms of Use, "Trademarks" shall be defined as the trademarks, trade names, logos, domain names, along with any other distinctive brand features of each party. Peplink hereby grants to You a non-transferable, non-sublicensable, non-exclusive license during the Term to display Peplink's Trademarks solely for the purpose of promoting or advertising that You use the API in accordance with these Terms of Use. You hereby grant to Peplink a nontransferable, nonexclusive license during the Term to use Your Trademarks to advertise that You are using the API and to the extent as may be necessary for Peplink to provide you with the API. You understand and agree that Peplink has the sole discretion to determine whether your use of Peplink Trademarks is in accordance with Peplink's standards for Trademark usage. Except as set forth in this Clause 8, nothing in the Terms of Use shall grant or shall be deemed to grant to one party any right, title or interest in or to the other party's Trademarks.

Attribution of Peplink's Third Party Data Providers. The mapping and routing images accessible by You by virtue of the API may contain the trade names, trademarks, logos, domain names, and other distinctive brand features of Peplink and its third party data providers. You may not delete or in any manner alter these trade names, trademarks, logos, domain names, and other distinctive brand features.

TERM AND TERMINATION
Term. The term of the Terms of Use shall commence on the date upon which You agree to the Terms of Use and shall continue in force thereafter, unless terminated as provided herein.

Termination. Peplink may change, suspend or discontinue all or any aspect of the API, including its availability, at any time, and may suspend or terminate Your use of the API at any time. In addition, either party may terminate the Terms of Use at any time, for any reason, or for no reason including, but not limited to, if You engage in any action that reflects poorly on Peplink or otherwise disparages or devalues the Peplink Trademarks or Peplink's reputation or goodwill. If You desire to terminate the Terms of Use, You must remove the API from Your application.

Effect of Termination. Upon the termination of the Terms of Use for any reason (i) all license rights granted herein shall terminate; (ii) You shall immediately delete any and all maps images and Peplink Trademarks; and (iii) You shall immediately cease all use of the API.

Survival. In the event of any termination or expiration of the Terms of Use for any reason, Clauses five through nine (5-9) shall survive termination. Neither party shall be liable to the other party for damages of any sort resulting solely from terminating the Terms of Use in accordance with its terms.

Equitable Remedies. You acknowledge that Your breach of API/license restrictions contained herein may cause irreparable harm to Peplink. Accordingly, You agree that, in addition to any other remedies to which Peplink may be legally entitled, Peplink shall have the right to seek immediate injunctive relief in the event of a breach of such clauses by You or any of Your officers, employees, consultants or other agents.

Entire Agreement. The Terms of Use constitute the entire agreement between You and Peplink and govern your use of the API, superseding any prior agreements between You and Peplink for the use of the API. You also may be subject to additional terms and conditions that may apply when You use or purchase certain other Peplink products or applications, affiliate applications, third-party content or third-party software.

Severability and Waiver. The failure of Peplink to exercise or enforce any right or provision of the Terms of Use shall not constitute a waiver of such right or provision. If any provision of the Terms of Use is found by a court of competent jurisdiction to be invalid, the parties nevertheless agree that the court should endeavor to give effect to the parties' intentions as reflected in the provision, and the other provisions of the Terms of Use remain in full force and effect.

Statute of Limitations. You agree that regardless of any statute or law to the contrary, any claim or cause of action arising out of or related to use of the API or the Terms of Use must be filed within one (1) month after such claim or cause of action arose or be forever barred.


Introduction

InControl 2 API uses the OAuth 2.0 protocol for authentication and authorization. It supports common OAuth 2.0 scenarios such as those for web server, installed, and client-side applications.

To begin, you will have to obtain an OAuth 2.0 client ID. If your app will access your InControl account only, you could get an ID by clicking on your username on the top of your InControl screen and scrolling down to the section "Client Application". If your app will allow any InControl users to sign-in and access their data, you can obtain an ID by sending an e-mail with your company name, company URL, app name, and redirect URI prefix to ic2api@peplink.com.

After you obtained a client ID, your client application should use it to request an authorization token from our authorization endpoints. Then it should request and extract an access token from the response from our token endpoint, and send the token to the InControl 2.0 API.

For more details about the OAuth 2.0, please refer to the RFC 6749.

You may also click the Get Access Token button below to obtain an access token and experiment the API below.

Unless specified, all timestamps returned from the API are also in the corresponding group's time zone.

  • Authorization Endpoint:
    • https://api.ic.peplink.com/api/oauth2/auth?client_id=[CLIENT_ID]&response_type=[code/token]&redirect_uri=[REDIRECT_URI]
  • Token Endpoint:
    • https://api.ic.peplink.com/api/oauth2/token
      • Required Parameters: client_id, client_secret, grant_type, redirect_uri, code
      • Method: POST
      • Form Encode: application/x-www-form-urlencoded
  • Access Token Location:
    • Authorization header with 'Bearer' prefix  [OR]
    • 'access_token' URL/form parameter
  • Token Response:
    • Content-Type: application/json
    • {"access_token":"your_access_token", "expires_in": 172799, "token_type":"Bearer", "refresh_token":"your_refresh_token"}
      • access_token: The access token string for API call.
      • expires_in: Duration of time in seconds the access token is granted for, default: 2 days.
      • token_type: Type of token
      • refresh_token: When access token expires, you may renew the access token through the OAuth "refresh_token" flow.
        By default, the refresh_token expires 30 days after the access token expires.
  • Usage Example:
    • Obtain Accessible organization list: https://api.ic.peplink.com/rest/o?access_token=[ACCESS_TOKEN]
    • Obtain group list: https://api.ic.peplink.com/rest/o/abcdef/g?access_token=[ACCESS_TOKEN]
  • Refresh token:
    • https://api.ic.peplink.com/api/oauth2/token
      • Method: POST
      • Encoding: application/x-www-form-urlencoded
      • Data: client_id=[your_client_id]&client_secret=[your_client_secret]&grant_type=refresh_token&refresh_token=[your_refresh_token]

    • API Request Rate Limit

  • The API Request Rate Limit is 20 requests per second per organization. A 429 response code will be returned if the rate is over the limit.

  • API Error Responses

    • When the access token expired or invalid
      • Response code: 401
      • {"error": "invalid_accessor","error_description":"Error message here"}

    • When the access token reach rate limit
      • Response code: 429
      • {"error": "rate_limit_exceeded","error_description":"Error message here"}

    • When the request is unauthorized
      • Response code: 401
      • {"error": "unauthorized","error_description":"Error message here"}

    • When the organization_id is invalid
      • Response code: 404
      • {"error": "org_not_found","error_description":"Error message here"}

    • Sample shell script implementation

  • A sample script can be downloaded from HERE

    • Obtain token using "client_credentials" flow example  [show]



    Obtain Access Token:


    [expand all] | [hide all] Pretty Print   Result data element only DELETE   PUT POST GET
  • GET /rest/o Get accessible organization list
  • GET /rest/o/{organization_id} Get organization info
  • GET /rest/o/{organization_id}/d Get an organization's devices list.
    When has_status is specified, for online devices, some status information (e.g. (WAN) interfaces, (data) usage, etc.) will be included. The system will trigger the devices to report the data in real-time. Before the fresh data (i.e. received in last 2 minutes) is available, no status information will be included. When fresh data is available (typically 1 to 2 seconds after a trigger), the status information will be included.
  • GET /rest/o/{organization_id}/d/basic Get an organization's devices list with most basic information only (for shorter load time with large device list)
  • GET /rest/o/{organization_id}/d/csv Get an organization's devices list in CSV Format
  • GET /rest/o/{organization_id}/d/{device_id} Get a device's details.
    For some dynamic information (e.g. interfaces (WAN) IP, IMSI, etc), if the device is offline, the previously stored data will be included. If the device is online, the system will trigger the device to report the data in real-time. Before the fresh data (i.e. received in last 2 minutes) is received, no dynamic data will be included. When the fresh data is available (typically 1 to 2 seconds after a trigger), the dynamic data will be included.
  • POST /rest/o/{organization_id}/delete_devices Delete devices from an organization
  • GET /rest/o/{organization_id}/delete_devices Get status for delete devices from an organization
  • PUT /rest/o/{organization_id}/device_tags Add Device Tags
  • DELETE /rest/o/{organization_id}/device_tags Delete Device Tags
  • GET /rest/o/{organization_id}/g Get an organization's group list
  • POST /rest/o/{organization_id}/g Create a group
  • GET /rest/o/{organization_id}/g/{group_id} Get a group's information
  • GET /rest/o/{organization_id}/g/{group_id}/acl Get Access Control List
  • PUT /rest/o/{organization_id}/g/{group_id}/acl Create Access Control List
  • GET /rest/o/{organization_id}/g/{group_id}/acl/{acl_id} Get Access Control List by Id
  • POST /rest/o/{organization_id}/g/{group_id}/acl/{acl_id} Update Access Control List
  • DELETE /rest/o/{organization_id}/g/{group_id}/acl/{acl_id} Delete Access Control List
  • GET /rest/o/{organization_id}/g/{group_id}/bandwidth Get bandwidth usage of devices in a group
  • GET /rest/o/{organization_id}/g/{group_id}/bandwidth/csv Download bandwidth usage in CSV format
  • GET /rest/o/{organization_id}/g/{group_id}/captive_portal_user_info Get captive portal user info
  • GET /rest/o/{organization_id}/g/{group_id}/captive_portal_user_info/csv Get captive portal user info in CSV format
  • GET /rest/o/{organization_id}/g/{group_id}/client Get a group's live clients list
  • GET /rest/o/{organization_id}/g/{group_id}/client/{client_id} Get a client's information in group level
  • GET /rest/o/{organization_id}/g/{group_id}/client/{client_id}/captive_portal_access_logs Get captive portal access logs by client
  • GET /rest/o/{organization_id}/g/{group_id}/client/{client_id}/captive_portal_user_info Get captive portal user info by client
  • GET /rest/o/{organization_id}/g/{group_id}/client/{client_id}/daily_usages Get a client's bandwidth usage in last 30 days
  • GET /rest/o/{organization_id}/g/{group_id}/client/{client_id}/daily_usages/csv Get a client's bandwidth usage in last 30 days in CSV format
  • GET /rest/o/{organization_id}/g/{group_id}/client_usage_summary Get group level client usage summary
  • GET /rest/o/{organization_id}/g/{group_id}/clone_config/{id} Get a master configuration
  • GET /rest/o/{organization_id}/g/{group_id}/clone_configs Get master configurations
  • GET /rest/o/{organization_id}/g/{group_id}/cp Get captive portals of a group
  • GET /rest/o/{organization_id}/g/{group_id}/cp/download Get captive portal contents
  • GET /rest/o/{organization_id}/g/{group_id}/cp/{cp_id} Get a group level captive portal
  • GET /rest/o/{organization_id}/g/{group_id}/cp/{cp_id}/captive_portal_user Get captive portal user info
  • GET /rest/o/{organization_id}/g/{group_id}/cp_usage_report Get captive portal usage reports
  • GET /rest/o/{organization_id}/g/{group_id}/cp_usage_report/csv Get captive portal usage reports in CSV format
  • GET /rest/o/{organization_id}/g/{group_id}/custom_portals Get custom captive portals
  • GET /rest/o/{organization_id}/g/{group_id}/d Get a group's device list.
    When has_status is specified, for online devices, some status information (e.g. (WAN) interfaces, (data) usage, etc.) will be included. The system will trigger the devices to report the data in real-time. Before the fresh data (i.e. received in last 2 minutes) is available, no status information will be included. When fresh data is available (typically 1 to 2 seconds after a trigger), the status information will be included.
  • GET /rest/o/{organization_id}/g/{group_id}/d/basic Get a group's device list with most basic information only (for shorter load time with large device list)
  • GET /rest/o/{organization_id}/g/{group_id}/d/csv Get group's device list in CSV Format
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id} Get a device's details.
    For some dynamic information (e.g. interfaces (WAN) IP, IMSI, etc), if the device is offline, the previously stored data will be included. If the device is online, the system will trigger the device to report the data in real-time. Before the fresh data (i.e. received in last 2 minutes) is received, no dynamic data will be included. When the fresh data is available (typically 1 to 2 seconds after a trigger), the dynamic data will be included.
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/air_monitor Get an AirProbe's AirMonitor data by date and time
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/air_monitor/chutil Get an AirProbe's AirMonitor Channel Util data by date and time
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/air_monitor/dates Get dates on which an AirProbe is with AirMonitor data
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/air_probe/performance_test Get performance test data
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/air_probe/performance_test_list Get performance test list
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/bandwidth Get a device's life-time, real-time, hourly, daily, monthly and per-minute reporting data
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/bandwidth/csv Get a device's bandwidth usage in CSV format
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/client Get device's live client list
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/client/{client_id} Get a client's information in device level
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/client/{client_id}/captive_portal_access_logs Get captive portal access logs by client
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/client/{client_id}/daily_usages Get a clients' bandwidth usage in device level in last 30 days
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/client/{client_id}/daily_usages/csv Get a clients' bandwidth usage in device level in last 30 days in CSV format
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/client_usage_summary Get device level client usage summary
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/config_backup Get a device's configuration file list
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/config_backup/{id} Get a device's configuration file
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/cp Get a device's captive portal list
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/cp/{cp_id} Get a device level captive portal
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/cp/{cp_id}/captive_portal_user Get captive portal user info
  • GET /rest/o/{organization_id}/g/{group_id}/d/{device_id}/cp_usage_report Get a captive portal's usage reports