Aruba Central Application Programming Interface

Aruba Central Application Programming Interface User Guide

Copyright Information Copyright 2016 Hewlett Packard Enterprise Development LP. Open Source Code This product includes code licensed under the GNU General Public License, the GNU Lesser General Public License, and/or certain other open source licenses. A complete machine-readable copy of the source code corresponding to such code is available upon request. This offer is valid to anyone in receipt of this information and shall expire three years following the date of the final distribution of this product version by Hewlett Packard Enterprise Company. To obtain such source code, send a check or money order in the amount of US $10.00 to: Hewlett Packard Enterprise Company Attn: General Counsel 3000 Hanover Street Palo Alto, CA 94304 USA Revision 01 October 2016 Aruba Central

Contents Contents 3 About this Guide 4 Related Documents 4 Contacting Support 4 Aruba Central APIs 5 API Gateway 5 Using OAuth 2.0 to Access API 5 Access and Refresh Tokens 5 Obtaining Tokens 5 Authorization Code Grant 6 Example 8 Refreshing a token 8 Example 9 Accessing APIs 9 Example 10 Viewing APIs 10 Viewing Tokens 11 Revoking Tokens 11 Adding a New Token 11 API Documentation 11 Aruba Central Contents 3

Chapter 1 About this Guide This guide describes how to use Aruba Central Application Programming Interface (API) to configure your apps. Related Documents In addition to this document, the Central product documentation includes the following documents: Aruba Central User Guide Aruba Central Getting Started Guide Aruba Central Online Help Aruba Central Release Notes Contacting Support Table 1: Contact Information Main Site Support Site Airheads Social Forums and Knowledge Base North American Telephone International Telephone Software Licensing Site End-of-life Information Security Incident Response Team arubanetworks.com support.arubanetworks.com community.arubanetworks.com 1-800-943-4526 (Toll Free) 1-408-754-1200 arubanetworks.com/support-services/contact-support/ licensing.arubanetworks.com arubanetworks.com/support-services/end-of-life/ Site: arubanetworks.com/support-services/security-bulletins/ Email: sirt@arubanetworks.com Aruba Central About this Guide 4

Chapter 2 Aruba Central APIs Central supports an Application Programming Interface (API) to allow developers to create and manage APIs. It supports polling-based and Representational State Transfer (REST)-based APIs. The REST APIs support HTTP GET operations by providing a specific URL for each query. The output for these operations is returned in the JSON format. API Gateway The API Gateway feature in Central supports the REST API for all Central services. This feature allows the Central users to write custom applications, embed, or integrate the APIs with their own applications. Using OAuth 2.0 to Access API For secure access to the APIs, the Central API Framework plug-in supports OAuth protocol for authentication and authorization. OAuth 2.0 is a simple and secure authorization framework. It allows applications to acquire an access token for Central through a variety of work flows supported within the OAuth2 specification. All OAuth2 requests must use the SSL endpoint available at https://app1-apigw.central.arubanetworks.com. Access and Refresh Tokens The access token is a string that identifies a user, app, or web page and is used by the app to access an API. The access tokens provide a temporary and secure access to the APIs. The access tokens have a limited lifetime. If the application uses web server or user-agent OAuth authentication flows, a refresh token is provided during authorization that can be used to get a new access token. If you are writing a long running applications (web app) or native mobile application you should refresh the token periodically. For more information, see Refreshing a token on page 8. Obtaining Tokens The users can generate the OAuth token using one of the following methods: Offline token download Authorization code grant Offline Token Mechanism To obtain tokens using the offline token method, complete the following steps: 1. Click Maintenance > API Gateway. The API Gateway page is displayed. 2. Click Authorized Apps & Tokens. 3. Click View Tokens. The Token List pop-up window opens. 4. To download tokens, click Download Token. Aruba Central Aruba Central APIs 5

Authorization Code Grant The following sections describe the procedures for obtaining the access tokens using the authorization code grant mechanism. Step 1 - Obtain Authorization Code To authenticate a user, access the following web page: https://app1-apigw.central.arubanetworks.com/oauth2/token/authorize/central. This endpoint is accessible over SSL. The HTTP (non-ssl) connections are redirected to the SSL port. Table 2: User Authentication and Session Validation URL https://app1- apigw.central.arubanetworks.com/oauth2/token/authorize/central Description The endpoint validates the user session. For Central, the SSO authentication page is presented. After successful authentication, a consent page is shown requesting the resource owner(the customer who has logged in) to give access to the APIs. The response is an authorization code in JSON that can be copied manually or automatically to obtain a token. The query parameters for the API are as follows: Table 3: Query Parameters For The API client_id A unique hexadecimal string A unique identifier that identifies the caller. The application developers can request a client ID and client secret key by registering with Aruba Technical Support. response_type code Use code to get the authorization code that can be exchanged for token. scope all or read Requests API permissions, all for read-write and read for read access. A JSON dictionary with the following keys is returned as a response. Table 4: JSON Response auth_code string A unique string with a TTL of 5 minutes, the code can be exchanged for a token to access APIs. Example Request URL https://app1-apigw.central.arubanetworks.com/oauth2/authorize/central?client_ id=6e44a1c7e3a84620b520f39fb71e6b55&response_type=code&scope=all Response "auth_code":"dd2ae8e9bdab4f2488630bbe57455412"} 6 Aruba Central APIs Aruba Central

Step 2 Exchange Code for a Token To authenticate the user, access the following URL: https://app1-apigw.central.arubanetworks.com/oauth2/token. This endpoint is accessible over SSL. The HTTP (non-ssl) connections are redirected to the SSL port. Table 5: Obtaining Access Token URL https://app1- apigw.central.arubanetworks.com/oauth2/token Description The endpoint is a POST call to get the access token using the authorization code obtained from the server. This exchange must be done within 300 seconds of obtaining authorization code from step 1. Otherwise, the API will return an error. The query parameters for the API are as follows: Table 6: Query Parameters For The API client_id client_secret grant_type A unique hexadecimal string A unique hexadecimal string authorization_ code A unique identifier that identifies the caller. The application developers can request a client ID and client secret key by registering with the Aruba Technical Support. The client_secret is a unique identifier provided to each developer at the time of registration. The application developers can request a client_id and client_secret by registering with the Aruba Technical Support. Use code to get the authorization code that can be exchanged for token. code auth_code received from step 1 The authorization code received from the authorization server. redirect_uri String The redirect URI must be the same as the one given at the time of registration. This is an optional parameter. A JSON dictionary with the following values is returned as a response. Table 7: JSON Response token_type bearer Identifies the token type. Only the bearer token type is supported. For more information, see https://tools.ietf.org/html/rfc6750. refresh_token string Refers to the refresh tokens that are used as credentials to renew or refresh the access token when the token expires without going through the complete authorization flow. A refresh token is a string representing the authorization granted to the client by the resource owner. expires_in seconds The expiration duration of the access token in seconds. access_token string Refers to the access tokens that are used as credentials to access the protected resources. An access token is a string representing an authorization issued to the client. Aruba Central Aruba Central APIs 7

Example Request URL (Method=POST) https://app1-apigw.central.arubanetworks.com/oauth2/token?client_ id=8cc10a1b50be42439a9a2d390d4b260b&grant_type=authorization_ code&code=dd2ae8e9bdab4f2488630bbe57455412&client_secret=5d2206390c67475886e0bd499098ff6c Response "refresh_token": "c089be0f6c784b0bbe996629ec2ea215", "token_type": "bearer", "access_token": "9249b5a1388749a5925031ead791b05f", "expires_in": 7200 } Refreshing a token To refresh the access token, access the following URL: https://app1-apigw.central.arubanetworks.com/oauth2/token This endpoint is accessible over SSL. The HTTP (non-ssl) connections are redirected to SSL port. Table 8: Refresh Tokens URL https://app1- apigw.central.arubanetworks.com/oauth2/token Description The endpoint is a POST call to refresh the access token using the refresh token obtained from the step 2. The query parameters for the API are as follows: Table 9: Query Parameters For Refresh Tokens client_id client_secret grant_type refresh_token A unique hexadecimal string A unique hexadecimal string refresh_ token refresh_ token received from step 2 A unique identifier that identifies the caller. The application developers can request a client ID and client secret key by registering with the Aruba Technical Support. The client secret is a unique identifier provided to each developer at the time of registration. The application developers can request a client ID and client secret by registering with the Aruba Technical Support. The grant_type must be refresh_token to refresh the token. A string representing the authorization granted to the client by the resource owner. A JSON dictionary with the following values is returned as a response. 8 Aruba Central APIs Aruba Central

token_type bearer Identifies the token type. Only the bearer token type is supported. For more information, see https://tools.ietf.org/html/rfc6750. refresh_token string Refresh tokens are credentials used to renew or refresh the access_token when it expires without going through the complete authorization flow. A refresh token is a string representing the authorization granted to the client by the resource owner. expires_in seconds The expiration duration of the access tokens in seconds. access_token string Access tokens are credentials used to access the protected resources. An access token is a string representing an authorization issued to the client. Example Request: ( Method = POST ) https://app1-apigw.central.arubanetworks.com/oauth2/token?client_ id=98273576d558401581c425d5bd9df213&grant_type=refresh_token&refresh_ token=1272ddc5f4c94683b7ac3080f39503f9&client_secret=e20f3fad10dc4c41bf291a49e85a3b29 Response "refresh_token": "bbf16f785a32435590627affd2a2ecdc", "token_type": "bearer", "access_token": "889479cac74e4b299723cc9a6f8f9d08", "expires_in": 7200 } Accessing APIs To access the API, use the following URL: https://app1-apigw.central.arubanetworks.com/. This endpoint is accessible over SSL and the HTTP (non-ssl) connections are redirected to the SSL port. Table 10: Accessing The API URL https://app1- apigw.central.arubanetworks.com/ Description The API gateway URL. All APIs can be accessed from this URL by providing a correct access token. The query parameters for the API are as follows: Table 11: Query Parameters For The API request_path URL Path UTL path of an API, for example, to access monitoring APIs, use the path /monitoring/v1/aps. access_token access_ token Pass the token string in URL parameter that is obtained in step 2. Aruba Central Aruba Central APIs 9

Example Request: (Method=Get) https://app1-apigw.central.arubanetworks.com/monitoring/v1/aps?access_ token=e325c0fb3f1547b5b735de3221690c2f Response: "aps": [ "firmware_version": "6.4.4.4-4.2.3.1_54637", "group_name": "00TestVRK", "ip_address": "10.29.18.195", "labels": [ "Filter_242", "Ziaomof", "roster", "242455", "Diegso" ], "macaddr": "6c:f3:7f:c3:5d:92", "model": "AP-134", "name": "6c:f3:7f:c3:5d:92", "radios": [ "band": 0, "index": 1, "macaddr": "6c:f3:7f:b5:d9:20", "status": "Down" }, "band": 1, "index": 0, "macaddr": "6c:f3:7f:b5:d9:30", "status": "Down" } ], "serial": "AX0140586", "status": "Down", "swarm_id": "e3bf1ba201a6f85f4b5eaedeead5e502d85a9aef58d8e1d8a0", "swarm_master": true } ], "count": 1 } Viewing APIs To view the APIs managed through Central, complete the following steps: 1. Click Maintenance > API Gateway. The API Gateway page shows the list of published APIs. 2. To view the details of an API, click Details. 3. To view the API documentation, click Documentation. The documentation is displayed in a new window. 10 Aruba Central APIs Aruba Central

Viewing Tokens To view tokens, complete the following steps: 1. Click Maintenance > API Gateway. The API Gateway page is displayed. 2. Click Authorized Apps & Tokens. 3. To view tokens, click View Tokens. Revoking Tokens To revoke tokens, complete the following steps: 1. Click Maintenance > API Gateway. The API Gateway page is displayed. 2. Click Authorized Apps & Tokens. 3. To view tokens, click View Tokens. The Token List pop-up window opens. 4. To revoke tokens, click Revoke Token. Adding a New Token To add a new token, complete the following steps: 1. Click Maintenance > API Gateway. The API Gateway page is displayed. 2. Click Authorized Apps & Tokens. 3. Click + to add a new token. 4. Enter the application name and then click Generate. API Documentation For a complete list of APIs and the corresponding documentation, see https://app1- apigw.central.arubanetworks.com/swagger/central. Aruba Central Aruba Central APIs 11