JSON Web Tokens and you!

Okay, so we're not about to replace the fountain of knowledge that is wikipedia any time soon, so if you've never heard of JWTs perhaps start here then come back! Oh and these people know what they're talking about as well.

Since JWTs are meant for M2M integration via APIs, we currently only support their administration via that interface. Check out the API page for a swagger file or just to peruse our spec.

Step 1 - Login

We've gone over logging into Skylight Analytics via the API before (i.e. Intro to REST APIs and Using APIs to Retrieve Session PM data), so to switch it up we'll go over the curl method.

Here's the login request in using curl. Notice the -v parameter - we need that so we can steal the auth token in the response to use in subsequent API requests

curl --location --request POST 'https://<ANALYTICS URL>/api/v1/auth/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=you@yourdomain.com' \
--data-urlencode 'password=yourpassword' -v

And the result is huge because of the -v, but look for the :

...
< HTTP/2 200
...
< authorization: Bearer MTYyNDU4NzY<yada yada yada>gG17D3sci8L
...
<payload with your dets confirming it worked>

Steal the auth token - the part after the Bearer.

Step 2 - Create the JWT

The specific API we're looking for is:
https://api.analytics.accedian.io/session.html#operation/CreateToken

Here is an example request:

curl --location --request POST 'https://**<analytics URL>**/api/v1/auth/tokens' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Cookie: NSREDIRECT=https://<ANALYTICS URL>/api/v1/auth/tokens; skylight-aaa=<AUTHTOKEN>' \
--data-raw '{
    "data": {
        "type": "tokens",
        "attributes": {
            "iss": "you@yourdomain.com",
            "sub": "ronald@acme.inc",
            "aud": "<tenant name>",
            "exp": <epoch integer, set for however long in the future you want this JWT valid for>
        }
    }
}'

And the response should just be the JWT. For security reasons, this is the only time you'll see that token - there are no second chances! So save it somewhere secure. There are other APIs to list or delete JWTs, but none will allow you to see the actual token, but the provisioning attributes.

Optional check it

Find a JWT and can't remember what it was for or want to double check the one you got, head over to JWT.io and use their debugger.

Step 3 - Use the JWT

Now go forth and embedded the login command in your scripts to auth your session prior to performing whatever other business you are trying to automate (provision users, metadata, or just retrieve PM data).

curl --location --request POST 'https://<ANALYTICS URL>/api/v1/auth/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=<JWT>' -v

Steal the AUTH TOKEN again and use it in your next API request, like to retrieve PM data. The following example produces an average aggregate packet loss % for the last day grouped by a metadata field in this system called "customer".

curl --location --request POST 'https://demo.labs.analytics.accedian.io/api/v3/metrics/groupBy' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Cookie: skylight-aaa=<AUTH TOKEN>' \
--data-raw '{
    "data": {
        "type": "groupByMetrics",
        "attributes": {
            "aggregation": "avg",
            "interval": "2021-06-24T02:45:42.945Z/2021-06-25T02:45:42.945Z",
            "groupingContext": {
                "strictGroupings": true,
                "groupings": [
                    {
                        "groupName": "customer",
                        "groupType": "meta"
                    }
                ]
            },
            "globalMetricFilterContext": {
                "objectType": [
                    "twamp-sl",
                    "twamp-pe",
                    "twamp-sf"
                ]
            },
            "metrics": [
                {
                    "direction": [
                        "0"
                    ],
                    "objectType": [
                        "twamp-sl",
                        "twamp-pe",
                        "twamp-sf"
                    ],
                    "metric": "packetsLostPct"
                }
            ],
            "queryContext": {
                "ignoreCleaning": false,
                "focusBusyHour": false,
                "ignoreMaintenance": false,
                "numResults": 5,
                "sorted": "desc"
            }
        }
    }
}'

Have fun!