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

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.

If user authentication is successful, the request will return HTTPHypertext 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 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, which must be used for all subsequent HTTP requests.

Example

Request Method: POSTThe 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 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):

Error Response:

Response Body (JSON):

Response Body (JSON):

Response Body (JSON):

Success Response:

Response Body (JSON):

Response Header:

Step 2: [Optional] Generating Client Credentials

To generate client credentials, use the following URIUniform 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 instance>/central/api/client_credentials?client_id=<client_id>

POST Request Body(JSON):

Request Header: (Values from login API request)

Response Body(JSON):

Response Body (JSON):

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 2: URL for to Generate an Authorization Code

URL	Description
https://apigw-<FQDN of the Aruba Central 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 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://apigw-<FQDN of the Aruba Central 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):

Error Response:

Response Body (JSON):

Response Body (JSON):

Response Body (JSON):

Success Response:

Response Body (JSON):

Response Header:

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 4: URL for to Generate an Auth Token

URL	Description
https://apigw-<FQDN of the Aruba Central 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 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	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 JSONJavaScript 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 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 instance>/oauth2/token?client_id=<Ccentral-API-app-clientid>&client_secret=xxxx&grant_type=authorization_code&code=xxxx \

Content -Type: application/json

Response:

Step 5: Refreshing a Token

You can use the refresh token obtained in the previous step to update the access token without repeating the entire authentication process. A refresh token is only required once your access token is expired. You can only refresh a token for a new access token every 15 minutes. For example, when you refresh a new token, you can use the provided access token for 2 hours. If you want a new access token, you have to again refresh the token after 15 minutes from its last refresh.

Table 7: URL to Refresh a Token

URL	Description
https://apigw-<FQDN of the Aruba Central 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 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 instance>/oauth2/token?client_id=<Ccentral-API-app-clientid>&client_secret=xxxx&grant_type=authorization_code&code=xxxx \

Response

Step 6: Deleting a Token

To delete the access token, access the following URLUniform 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 instance>/oauth2/token	This endpoint is accessible over SSLSecure 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 SSL port. Customer ID is a string.

Example

Method : DELETE

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

JSON Body:

Headers:

Content-Type: application/json

X-CSRF-Token: <CSRF_token_obatained_from_login_API>

Cookie: "session=<session_obatained_from_login_API>"