Obtaining Token Using OAuth Grant Mechanism

The following section describes the steps for obtaining the access token and refresh token using the authorization code grant mechanism:

• Step 1: Authenticate a User and Create a User Session
• Step 2: [Optional] Generating Client Credentials
• Step 3: Generate Authorization Code
• Step 4: Exchange Auth Code for a Token
• Step 5: Refreshing a Token
• Step 6: Deleting a Token

Step 1: Authenticate a User and Create a User Session

The following API authenticates a user and returns a user session value that can be used to create future requests for a client with the specified username and password. It is assumed that you already have a client ID for your application. For more information on how to create an application and obtain tokens, see Creating Application and Token.

Domain URL allow you to log in to the API gateway server and to establish the user session. This endpoint is accessible over SSL Secure Sockets Layer. SSL is a computer networking protocol for securing connections between network application clients and servers over the Internet., and HTTP Hypertext Transfer Protocol. The HTTP is an application protocol to transfer data over the web. The HTTP protocol defines how messages are formatted and transmitted, and the actions that the w servers and browsers should take in response to various commands. (non-SSL) connections are redirected to SSL port. The following table lists the region specific domain URLs Uniform Resource Locator. URL is a global address used for locating web resources on the Internet. for accessing the API gateway.

If user authentication is successful, the request will return HTTP code 200 and the response header will include the following attributes.

Table 1: Authentication and User session Response Codes

Header Key example	Values	Description
https://app1--<FQDN of the HPE Aruba Networking Centralinstance>.com/oauth2/authorize/central/api/login?client_id=<client_id>	csrftoken=xxxx; session=xxxx	The server returns a CSRF token and identifies the user session, which must be used for all subsequent HTTP requests.

Example

Request Method: POST The HTTP POST method is used for transferring data from a client (browser) to a server using the HTTP protocol. The POST method is considered a secure way of transferring data from a client as it carries the request parameter in the message body and does not append it in the URL string.

URL: https://app1- -<FQDN of the HPE Aruba Networking Centralinstance>.com/oauth2/authorize/central/api/login?client_id=<client_id> HTTP/1.1

Host: app1--<FQDN Fully Qualified Domain Name. FQDN is a complete domain name that identifies a computer or host on the Internet. of the HPE Aruba Networking Centralinstance>.com

Request Header:

Accept: application/json

Content -Type: application/json

POST Request Body(JSON):

{

"username": "xxxxx",

"password": "xxxxx"

}

Error Response:

400: Bad Request

Response Body (JSON):

{

"extra": {},

"message": "<error string>"

}

401: Auth failure

Response Body (JSON):

{

"message": "Auth failure",

"status": false

}

429: API rate limit exceeded

Response Body (JSON):

{

"message": "API rate limit exceeded. Please retry after xxxx seconds"

}

Success Response:

200: OK

Response Body (JSON):

{

"status": true

}

Response Header:

Set-Cookie: csrftoken=xxxx;session=xxxx;

Step 2: [Optional] Generating Client Credentials

The following API can be used to generate client credentials for a specific tenant using your Managed Service Provider (MSP Managed Service Provider. The Managed Service Provider (MSP) mode is a multi-tenant operational mode that Aruba Central accounts can be converted into, provided these accounts have subscribed to the Aruba Central app.) Client ID.

The rate limit to generate client credentials for a client ID is restricted to 2 seconds.

Table 2: URL to Generate Client Credentials

URL example	Description
https://app1--<FQDN of the HPE Aruba Networking Centralinstance>.com/oauth2/authorize/central/api/client_credentials?client_id=<msp_client_id>	The <msp_client_id> variable is the client ID given from Central to that a Managed Service Provider that user registered the application.

Example

Request Method: POST

URI—https://app1--<FQDN of the HPE Aruba Networking Centralinstance>.com/oauth2/authorize/central/api/client_credentials?client_id=<msp_client_id>

POST Request Body(JSON):

{

"customer_id": "<tenant_id>"

}

Request Header: (Values from login API request)

Set-Cookie: csrftoken=xxxx;session=xxxx;

Response Body(JSON):

{

"client_id": "<new-client-id>",

"client_secret": <new-client-secret>"

}

Error Response

429: API rate limit exceeded

Response Body (JSON):

{

"message": "API rate limit exceeded. Please retry after xxxx seconds"

}

Step 3: Generate Authorization Code

After the user is authenticated and you have a valid session for that user, use this API to get authorization code. The authorization code is valid only for 5 minutes and must be exchanged for a token within that time.

Table 3: URL for to Generate an Authorization Code

URL example	Description
https://app1 -<FQDN of the HPE Aruba Networking Centralinstance>.com/oauth2/authorize/central/api/?client_id=<client_id>&response_type=code&scope=all HTTP/1.1	The endpoint is a POST call to get an authorization code.

Query parameters for this API are as follows:

Table 4: Query Parameters for the Auth Code API

Parameter	Values	Description
client_id	client_id is a unique hexadecimal string	The client_id is a unique identifier that identifies the caller. Application developers obtain a client ID and a client secret when they register with the API gateway admin.
response_type	code	Use code as the response type to get the authorization code that can be exchanged for token
scope	all or read	Requested API permissions may be either all (for both read and write access) or read for read-only access.

Example

Request Method: POST

URL: https://app1 -<FQDN of the HPE Aruba Networking Centralinstance>.com/oauth2/authorize/central/api/?client_id=<client_id>&response_type=code&scope=all HTTP/1.1

Host: app1--<FQDN of the HPE Aruba Networking Centralinstance>.com

Request Header:

Accept: application/json Cookie: “session=xxxx” X-CSRF-Token: xxxx

Content -Type: application/json

POST Request Body(JSON):

{

"customer_id": "xxxxx"

}

Error Response:

400: Bad Request

Response Body (JSON):

{

"extra": {},

"message": "<error string>"

}

401: Auth failure

Response Body (JSON):

{

"message": "Auth failure",

"status": false

}

429: API rate limit exceeded

Response Body (JSON):

{

"message": "API rate limit exceeded. Please retry after xxxx seconds"

}

Success Response:

200: OK

Response Body (JSON):

{

" auth_code ": “xxxx”

}

Response Header:

Set-Cookie: csrftoken=xxxx;session=xxxx;

Step 4: Exchange Auth Code for a Token

Once you have an authorization code, you just use that code to request an access from the server. The exchanges should be done within 300 seconds of obtaining the auth code from the previous step, or the API will return an error.

Table 5: URL for to Generate an Auth Token

URL example	Description
https:// app1 -<FQDN of the HPE Aruba Networking Centralinstance>.com/oauth2/token	The endpoint is a POST call to get an access token using the authorization code obtained from the server.

Query parameters for this API are as follows:

Table 6: Query Parameters for the Auth Code API

Parameter	Values	Description
client_id	client_id is a unique hexadecimal string	The client_id is a unique identifier that identifies the caller. Application developers obtain a client ID and a client secret when they register with the API gateway admin.
client_secret	client_secret is a unique hexadecimal string	The client_secret is a unique identifier provided to each developer at the time of registration. Application developers can obtain a client ID and client secret when they register with the API gateway admin.
grant_type	authorization_ code	Use code to get the authorization code that can be exchanged for the token.
code	auth_code received from step 1	The authorization code received from the authorization server.
redirect_uri Uniform Resource Identifier. URI identifies the name and the location of a resource in a uniform format.	string	The redirect URI must be the same as the one given at the time of registration. This is an optional parameter.

The response to this API query is a JSON JavaScript Object Notation. JSON is an open-standard, language-independent, lightweight data-interchange format used to transmit data objects consisting of attribute–value pairs. JSON uses a "self-describing" text format that is easy for humans to read and write, and that can be used as a data format by any programming language. dictionary with following values:

Table 7: Auth Token Values

Parameter	Values	Description
token_type	bearer	Identifies the token type. Central supports only the bearer token type (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 repeating the complete authentication flow. A refresh token is a string representing the authorization granted to the client by the resource owner.
expires_in	seconds	The lifetime, in seconds, of the access token.
access_token	string	Access tokens are credentials used to access protected resources. An access token is a string representing an authorization issued to the client.

Example

Request Method: POST

URL: https: //apigw- -<FQDN of the HPE Aruba Networking Centralinstance>.com/oauth2/token

Content -Type: application/json

Body Parameters: Enter the parameter values to call the API

• client_id
• client_secret
• grant_type
• code

Response:

{

"refresh_token": "xxxx",

"token_type": "bearer",

"access_token": "xxxx",

"expires_in": 7200

}

Step 5: Refreshing a Token

You can update the access token without having to repeat the authentication process by using the refresh token obtained in the previous step. Below are some of the important points to note:

• A token created on Central API Gateway contains access and refresh tokens, and is available for 15 days.
• An access token is valid for 2 hours (7200 seconds).
• On refreshing the access token consecutively within 15 minutes, you obtain the same access token. To generate a new access token you must wait for 15 minutes before you refresh the access token.
• If the token is not used or refreshed for a period of 15 days, it is revoked from Central API Gateway.
• After a token is revoked, you have to add or generate a new token through the API Gateway.
• It is recommended to refresh the access token when it is invalid or at least once within 15 days so that Central can honor refreshing the token and does not revoke it.

Table 8: URL to Refresh a Token

URL example	Description
https://app1- -<FQDN of the HPE Aruba Networking Centralinstance>.com/oauth2/token	The endpoint is a POST call to refresh the access token using the refresh token obtained from the server

Query parameters for this API are as follows:

Table 9: Query Parameters for Refresh Tokens

Parameter	Value	Description
client_id	client_id is a unique hexadecimal string	The client_id is a unique identifier that identifies the caller. Application developers obtain a client ID and a client secret when they register with the API gateway admin.
client_secret	client_secret is a unique hexadecimal string	The client_secret is a unique identifier provided to each developer at the time of registration. Application developers obtain a client ID and a client secret when they register with the API gateway admin.
grant_type	refresh_token	Specify refresh_token as the grant type to request that an authorization code be exchanged for a token
refresh_token	string	A string representing the authorization granted to the client by the resource owner.

The response to this API query is a JSON dictionary with following values:

Parameter	Value	Description
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

Method: POST

https://apigw- -<FQDN of the HPE Aruba Networking Centralinstance>.com/oauth2/token?client_id=<Central-API-app-clientid>&client_secret=xxxx&grant_type=refresh_token&refresh_token=xxxx

Response

{

"refresh_token": "xxxx",

"token_type": "bearer",

"access_token": "xxxx",

"expires_in": 7200

}

Step 6: Deleting a Token

To delete the access token, access the following URL:

Table 10: URL to Delete a Token

URL example	Description
https://app1- -<FQDN of the Aruba Centralinstance>.com/oauth2/api/tokens	This endpoint is accessible over SSL. The HTTP (non-SSL) connections are redirected to SSL port. Customer ID is a string.

Example

Method : DELETE

URL:https://app1- -<FQDN of the HPE Aruba Networking Centralinstance>.com/oauth2/api/tokens

JSON Body:

{

"access_token": "<access_token_to_be_deleted>"

}

Headers:

Content-Type: application/json

X-CSRF-Token: <CSRF_token_obatained_from_login_API>

Cookie: "session=<session_obatained_from_login_API>"