This page guides you through the usage of the AGILITY API to help you get started integrating and using the AGILITY API to analyze network traces.

Prerequisites

Please ensure that you have the necessary credentials and permissions to access the API (login ID and password) from your administrator.

Note: when using the Community version of AGILITY, you will need to create an account using your email address instead of through your LinkedIn or Google account.

Overview

The AGILITY API is designed for system integrators and developers to enable advanced analysis on network traces, specializing in root cause analysis for call flows. The API supports file formats such as .PCAP, .PCAPNG, .CAP, and .ZIP.

API base URL

Use the base URL to access the OpenAPI documentation:

http(s)://<YOUR_PUBLIC_DN>/cv/api/public/docs

(example: https://agility-community.b-yond.com/cv/api/public/docs ).

Authentication

Use the OAuth2 Password Flow to request an access_token.

Request the token

Endpoint

POST /cv/auth/realms/agility/protocol/openid-connect/token

Provide your username, password, and the client_id (which is public and provided as d0d8b0d806f9) in your request.

Headers

Content-Type: application/x-www-form-urlencoded

Body

grant_type: password
client_id: d0d8b0d806f9
username: Your registered user name.
password: Your password.
scope: openid

Example cURL request

curl -X POST https://cv-dev.b-yond.com/cv/auth/realms/agility/protocol/openid-connect/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=password&client_id=d0d8b0d806f9&username=YOUR_USERNAME&password=YOUR_PASSWORD&scope=openid"

Replace YOUR_USERNAME and YOUR_PASSWORD with your credentials.

Response

Upon successful authentication, you'll receive a JSON response containing the id_token among other tokens.

Use the value of YOUR_ID_TOKEN in your subsequent API requests as a Bearer Token to authenticate your actions.
Use the REFRESH_TOKEN_VALUE to obtain a new token as described in the next section.

{
    "access_token": "ACCESS_TOKEN_VALUE",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "REFRESH_TOKEN_VALUE",
    "id_token": "YOUR_ID_TOKEN",
    ...
}

In the example above, the token expires in 300 second (5 min) while the refresh_token is valid for 1800 second (30 min).

Note: Always keep your id_token, access_token, and refresh_token secure. Do not expose them in client-side scripts or other insecure locations.

Handling expired tokens

When an access token expires, AGILITY API will no longer accept incoming request and will redirect you to the login page. We recommend that you request a new id_token using the refresh token request if it still valid or just re-authenticate.

Use these steps to handle expired tokens and ensure continuous access to the AGILITY API without requiring users to re-authenticate.

To refresh an expired token, follow these steps:

Make a refresh token request: Send a POST request to the token URL with the required parameters to refresh the token. Use the refresh token received during the initial authentication.
Example Request:
POST /cv/auth/realms/agility/protocol/openid-connect/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token &refresh_token=[Your Refresh Token] &client_id=d0d8b0d806f9
Receive a new id_token: If the refresh token is valid, AGILITY will respond with a new access token and potentially a new refresh token.
Example Response:
Update your authorization: Use the new access token in your request headers for subsequent API requests.

Note: Remember to securely store and manage the refresh token, as it provides long-term access to the API and should be protected from unauthorized access.

Next: Use the API endpoints.

AGILITY Documentation

Use the AGILITY API