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.

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

Values

Description

https://app1- apigw.central.arubanetworks.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- apigw.central.arubanetworks.com/oauth2/authorize/central/api/login?client_id=<client_id> HTTP/1.1

Host: app1-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;

The csrf token value received in the successful response message must be used as a parameter for all subsequent POST/PUT requests. The session value must also be used for all subsequent requests to maintain the user session context.

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) Client ID.

Table 2: URL to Generate Client Credentials

URL

Description

https://app1-apigw.central.arubanetworks.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

URIhttps://app1-apigw.central.arubanetworks.coms/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"

}

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

Description

https://app1 apigw.central.arubanetworks.com/oauth2/authorize/central/api

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 - apigw.central.arubanetworks.com/oauth2/authorize/central/api/?client_id=<client_id>&response_type=code&scope=all HTTP/1.1

Host: app1-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”

}

Pass the csrf-token value you obtained in step one in the request header, otherwise the request will be rejected. Note the auth_code value in the response, as you will use this code to obtain an OAuth Open Standard for Authorization. OAuth is a token-based authorization standard that allows websites or third-party applications to access user information, without exposing the user credentials. token.

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

Description

https:// app1- apigw.central.arubanetworks.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-prod2.central.arubanetworks.com/oauth2/token?client_id=<Ccentral-API-app-clientid>&client_secret=xxxx&grant_type=authorization_code&code=xxxx \

Content -Type: application/json

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).
  • 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

Description

https://app1-apigw.central.arubanetworks.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-prod2.central.arubanetworks.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

Description

https://app1-apigw.central.arubanetworks.com/oauth2/token

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