The following shows how to generate the jwt-usage-by-endpoint
report using either the Reporting API's Generate a report POST operation or the Get a cacheable report GET operation. Details about each report's supported products, metrics, filters, and available data intervals are also available dynamically by running the API's Get a report type operation, also shown below. See also other available reports.
Report definition
Provides information about the usage of your JSON Web Tokens by API endpoint.
Business object: cpcode
Data available for: 90 days
Required products: API Gateway
Available metrics
Metric | Description |
---|---|
Data metrics | |
edgeHits | The request count. |
Summary metrics | |
edgeHitsMax | The highest number of requests. |
edgeHitsMin | The lowest number of requests. |
edgeHitsTotal | The total number of edge requests for given objects and filters. |
Available filters
Filter | Type | Description |
---|---|---|
Optional filters | ||
endpoint_id | Integer | The ID of an API configuration registered with Akamai. |
error_state | Enumeration | A JWT-related reason for rejecting a request. Possible values are o: success/ok; u: unknown JWT or key definition; f: invalid token format; d: base64-decoding errors; p: JSON parsing errors; a: unsupported algorithm; j: invalid token type in the header; s: signature mismatch; t: failed timestamp claim; c: failed claim check; k: missing required claim; z: all other errors. |
p : JSON parsing errors | ||
a : unsupported algorithm | ||
c : failed claim check | ||
s : signature mismatch | ||
d : base64-decoding errors | ||
t : failed timestamp claim | ||
u : unknown JWT or key definition | ||
f : invalid token format | ||
j : invalid token type in the header | ||
z : all other errors | ||
k : missing required claim | ||
o : success/ok | ||
failed_claim | String | A JWT claim that failed the validation. Possible values are iss: issuer of the claim; sub: subject of this token; aud: audiences of this token; exp: expiration time; nbf: not before; alg: unsupported algorithm; typ: unsupported type. |
POST request
POST /reporting-api/v1/reports/jwt-usage-by-endpoint/versions/1/report-data{?start,end}
Sample: /reporting-api/v1/reports/jwt-usage-by-endpoint/versions/1/report-data?start=2020-05-01T00%3A00%3A00Z&end=2020-06-01T00%3A00%3A00Z
Query parameters
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
start | String | 2020-05-01T00:00:00Z | Specifies the start of the reported period as an ISO-8601 timestamp with optional time zone. The report includes data that matches the start value's timestamp. |
end | String | 2020-06-01T00:00:00Z | Specifies the end of the reported period as an ISO-8601 timestamp with optional time zone. The report excludes any data that matches the end value's timestamp. |
JSON request members
Member | Type | Description |
---|---|---|
objectIds | Array | Specifies the set of cpcode values you want to report on. |
objectIds | Enumeration | As an alternative to an array of ID values, specify all as a string for unfiltered data. Either way, objectIds is required. |
metrics | Array | The set of desired metrics. If omitted, the report includes all available metrics. |
filters | Map of Arrays | Specifies a set of custom filters, with each filter's name keying an array with each filter's set of values. |
Request body:
{
"objectIds": [
"55232",
"23433",
"32433"
],
"metrics": [
"edgeHits",
"edgeHitsMax",
"edgeHitsMin",
"edgeHitsTotal"
],
"filters": {
"endpoint_id": [
"577597",
"577596"
],
"error_state": [
"a",
"t"
],
"failed_claim": [
"nbf",
"typ"
]
}
}
GET request
GET /reporting-api/v1/reports/jwt-usage-by-endpoint/versions/1/report-data{?start,end,objectIds,allObjectIds,metrics,filters}
Sample: /reporting-api/v1/reports/jwt-usage-by-endpoint/versions/1/report-data?start=2020-05-01T00%3A00%3A00Z&end=2020-06-01T00%3A00%3A00Z&objectIds=55232,23433,32433&metrics=edgeHits%2CedgeHitsMax&filters=endpoint_id%3D577598%2Cendpoint_id%3D577597%2Cerror_state%3Da%2Cerror_state%3Ds
Query parameters
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
start | String | 2022-06-23T13:55:00Z | Specifies the start of the reported period as an ISO-8601 timestamp with optional time zone. The report includes data that matches the start value’s timestamp. |
end | String | 2022-06-23T14:15:00Z | Specifies the end of the reported period as an ISO-8601 timestamp with optional time zone. The report excludes any data that matches the end value’s timestamp. |
Optional | |||
allObjectIds | Boolean | true | As an alternative to objectIds , enabling this generates a report that includes all IDs available for the cpcode objectType. This parameter is ignored if the request also specifies a set of objectIds. |
objectIds | String | 55232,23433,32433 | As an alternative to allObjectIds , specifies the set of unique IDs for the cpcode objectType you want to report on, formatted as a comma-delimited list. |
metrics | String | edgeHits,edgeHitsMax | Specifies a comma-separated list of metrics to include in the report, otherwise all metrics if omitted. The set of available metrics depends on the type of report. URL-encode the entire value in the GET request. |
filters | String | endpoint_id=577598,endpoint_id=577597,error_state=a,error_state=s | Specifies criteria to filter the report's data. The set of available filters depends on the type of report. Separate each filter name and value with an equals (= ) character, and separate various name/value pairs with commas (, ). To specify more than one filter value, repeat the filter name. See the accompanying example for guidance. URL-encode the entire value in the GET request. |
JSON response
Status 200 application/json
Response body:
{
"metadata": {
"name": "jwt-usage-by-endpoint",
"version": "1",
"outputType": "FLAT",
"groupBy": [
"endpoint_id",
"error_state",
"failed_claim"
],
"start": "2020-05-01T00:00:00Z",
"end": "2020-06-01T00:00:00Z",
"availableDataEnds": null,
"suggestedRetryTime": null,
"rowCount": 4,
"filters": [
{
"name": "endpoint_id",
"values": [
"577599",
"577597"
]
},
{
"name": "error_state",
"values": [
"f",
"d"
]
},
{
"name": "failed_claim",
"values": [
"alg",
"iss"
]
}
],
"columns": [
{
"name": "groupBy",
"label": "endpoint_id"
},
{
"name": "groupBy",
"label": "error_state"
},
{
"name": "groupBy",
"label": "failed_claim"
},
{
"name": "edgeHits",
"label": "Edge Hits"
}
],
"objectType": "cpcode",
"objectIds": [
"55232",
"23433",
"32433"
]
},
"data": [
{
"endpoint_id": "577595",
"error_state": "t",
"failed_claim": "sub",
"edgeHits": "4844"
},
{
"endpoint_id": "577598",
"error_state": "f",
"failed_claim": "sub",
"edgeHits": "3082"
},
{
"endpoint_id": "577599",
"error_state": "p",
"failed_claim": "typ",
"edgeHits": "3641"
},
{
"endpoint_id": "577597",
"error_state": "s",
"failed_claim": "typ",
"edgeHits": "2313"
}
],
"summaryStatistics": {
"edgeHitsMax": {
"value": "3115",
"details": {}
},
"edgeHitsMin": {
"value": "4293",
"details": {}
},
"edgeHitsTotal": {
"value": "1695",
"details": {}
}
}
}
CSV response
Status 200 text/csv
Response Body:
#METADATA_START
name,jwt-usage-by-endpoint
version,1
source,jwt-usage-by-endpoint/versions/1
groupBy,endpoint_id,error_state,failed_claim
start,2020-05-01T00:00:00Z
end,2020-06-01T00:00:00Z
availableDataEnds,
suggestedRetryTime,
rowCount,4
objectType,cpcode
objectIds,55232,23433,32433
endpoint_id,577599,577597
error_state,f,d
failed_claim,alg,iss
#METADATA_END
#SUMMARYSTATISTICS_START
edgeHitsMax,3115
edgeHitsMin,4293
edgeHitsTotal,1695
#SUMMARYSTATISTICS_END
#COLUMNS_START
endpoint_id,error_state,failed_claim,edgeHits
#COLUMNS_END
#DATA_START
577595,t,sub,4844
577598,f,sub,3082
577599,p,typ,3641
577597,s,typ,2313
#DATA_END
Get report details
This sample Get a report type operation gets the same information you need to run the jwt-usage-by-endpoint
report as provided in this reference documentation, but available dynamically to your API client application.
GET /reporting-api/v1/reports/jwt-usage-by-endpoint/versions/1
Status 200 application/json
Response body:
{
"name": "jwt-usage-by-endpoint",
"description": "Provides information about the usage of your JSON Web Tokens by API endpoint.",
"businessObjectName": "cpcode",
"version": 1,
"status": "PUBLISHED",
"deprecated": false,
"timeBased": false,
"outputType": "FLAT",
"requiredProducts": [
"API Gateway"
],
"requiredRoles": [
"API Gateway Viewer",
"API Gateway Administrator"
],
"available": true,
"metrics": [
{
"name": "edgeHits",
"description": "The request count.",
"label": "Edge Hits",
"unit": "COUNT",
"summaryStatistic": false
},
{
"name": "edgeHitsMax",
"description": "The highest number of requests.",
"label": "Edge Hits Max",
"unit": "COUNT",
"summaryStatistic": true
},
{
"name": "edgeHitsMin",
"description": "The lowest number of requests.",
"label": "Edge Hits Min",
"unit": "COUNT",
"summaryStatistic": true
},
{
"name": "edgeHitsTotal",
"description": "The total number of edge requests for given objects and filters.",
"label": "Total Edge Hits",
"unit": "COUNT",
"summaryStatistic": true
}
],
"groupOutlyingValues": {
"enabled": false
},
"groupBy": [
"endpoint_id",
"error_state",
"failed_claim"
],
"filters": [
{
"name": "failed_claim",
"type": "string",
"description": "A JWT claim that failed the validation. Possible values are iss: issuer of the claim; sub: subject of this token; aud: audiences of this token; exp: expiration time; nbf: not before; alg: unsupported algorithm; typ: unsupported type.",
"required": false
},
{
"name": "error_state",
"type": "enum",
"description": "A JWT-related reason for rejecting a request. Possible values are o: success/ok; u: unknown JWT or key definition; f: invalid token format; d: base64-decoding errors; p: JSON parsing errors; a: unsupported algorithm; j: invalid token type in the header; s: signature mismatch; t: failed timestamp claim; c: failed claim check; k: missing required claim; z: all other errors.",
"values": [
{
"value": "p",
"description": "JSON parsing errors"
},
{
"value": "a",
"description": "unsupported algorithm"
},
{
"value": "c",
"description": "failed claim check"
},
{
"value": "s",
"description": "signature mismatch"
},
{
"value": "d",
"description": "base64-decoding errors"
},
{
"value": "t",
"description": "failed timestamp claim"
},
{
"value": "u",
"description": "unknown JWT or key definition"
},
{
"value": "f",
"description": "invalid token format"
},
{
"value": "j",
"description": "invalid token type in the header"
},
{
"value": "z",
"description": "all other errors"
},
{
"value": "k",
"description": "missing required claim"
},
{
"value": "o",
"description": "success/ok"
}
],
"required": false
},
{
"name": "endpoint_id",
"type": "int",
"description": "The ID of an API configuration registered with Akamai.",
"required": false
}
],
"intervals": [
"MONTH",
"WEEK",
"DAY",
"HOUR",
"FIVE_MINUTES"
],
"dataRetentionDays": 90,
"links": [
{
"rel": "self",
"href": "/reporting-api/v1/reports/jwt-usage-by-endpoint/versions/1"
},
{
"rel": "versions",
"href": "/reporting-api/v1/reports/jwt-usage-by-endpoint/versions"
},
{
"rel": "all-reports",
"href": "/reporting-api/v1/reports"
},
{
"rel": "execute-report",
"href": "/reporting-api/v1/reports/jwt-usage-by-endpoint/versions/1/report-data"
}
]
}