Obtaining Token Using OAuth Grant Mechanism

The following section describes the steps to obtain the access token, and refresh the token using the authorization code grant mechanism:

Step 1: Authenticate a User and Create a User Session

The following API authenticates a user and returns a user session value. You can use the session value to create future requests for a client with the specified username and password. As a prerequisite, you must have a client ID for your application. For more information on how to create an application and obtain tokens, see Creating Application and Token.

If user authentication is successful, the request will return 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. code 200, and the response header will include the following attributes.

Table 1: Authentication and User session Response Codes

Header Key	Values	Description
https://apigw-<FQDN of the Aruba Central On-Premises instance>/oauth2/authorize/central/api/login?client_id=<client_id>	csrftoken=xxxx; session=xxxx	The server returns a CSRF token and identifies the user session. Use the CSRF token and session value 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://apigw-<FQDN of the Aruba Central On-Premises instance>/oauth2/authorize/central/api/login?client_id=<client_id>

Host: apigw.central.arubanetworks.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"

}

Success Response:

200: OK

Response Body (JSON):

{

"status": true

}

Response Header:

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

Step 2: [Optional] Generating Client Credentials

To generate client credentials, use the following URI Uniform Resource Identifier. URI identifies the name and the location of a resource in a uniform format. and the request method.

Example

Request Method: POST

URI—https://apigw-<FQDN of the Aruba Central On-Premises instance>/central/api/client_credentials?client_id=<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"

}

Step 3: Generate Authorization Code

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

Table 2: URL for to Generate an Authorization Code

URL	Description
https://apigw-<FQDN of the Aruba Central On-Premises instance>/oauth2/authorize/central/api	The endpoint is a POST call to get an authorization code.

Query parameters for this API are as follows.

Table 3: 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. You can exchange the authorization code for a 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://apigw-<FQDN of the Aruba Central On-Premises instance>/oauth2/authorize/central/api/?client_id=<client_id>&response_type=code&scope=all HTTP/1.1

Host: apigw.central.arubanetworks.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"

}

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

After you have an authorization code, you use the code to request access from the server. The exchange must be done within 300 seconds of obtaining the auth code in the previous step. If the exchange is not done withing 300 seconds, the API will return an error.

Table 4: URL for to Generate an Auth Token

URL	Description
https://apigw-<FQDN of the Aruba Central On-Premises instance>/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 5: 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 the code to get the authorization code. You can use the authorization code to exchange for the token.
code	auth_code received in step one	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. The redirect_uri 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 the following values.

Table 6: 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 Aruba Central On-Premises instance>/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. The following list 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).
• 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 7: URL to Refresh a Token

URL	Description
https://apigw-<FQDN of the Aruba Central On-Premises instance>/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 8: 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 the 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 Aruba Central On-Premises instance>/oauth2/token?client_id=<Ccentral-API-app-clientid>&client_secret=xxxx&grant_type=authorization_code&code=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 Uniform Resource Locator. URL is a global address used for locating web resources on the Internet. .

Table 9: URL to Delete a Token

URL	Description
https://apigw-<FQDN of the Aruba Central On-Premises instance>/oauth2/token	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. . The HTTP (non-SSL) connections are redirected to the SSL port. Customer ID is a string.

Example

Method: DELETE

URL:https://apigw-<FQDN of the Aruba Central On-Premises instance>/oauth2/api/tokens

JSON Body:

{

"access_token": "<access_token_to_be_deleted>", "customer_id": "<customer_id_to_whom_token_belongs_to>"

}

Headers:

Content-Type: application/json

X-CSRF-Token: <CSRF_token_obatained_from_login_API>

Cookie: "session=<session_obatained_from_login_API>"