API Manager Log Service API (Beta)

Introduction

As an alternative to downloading an API log file by clicking Download as CSV on the API Logs page, you can retrieve an API log file using a REST API. This requires the use of either command line utilities such as curl or applications such as Postman.

To use the API Manager Log Service API (Beta), after enabling API logs for the API Manager API, follow these steps:

1. Retrieve an authentication token using the User Service Controller API. This token is required in order to use the API Manager Log Service API (Beta).

   • If your Harmony organization does not have two-factor authentication (TFA) enabled, retrieve your authentication token with a standard login request.

   • If your Harmony organization has TFA enabled, retrieving the authentication token requires two requests:

     1. Retrieve a TFA code

     2. Use the TFA code to retrieve an authentication token

2. Retrieve the log file using the API Manager Log Service API (Beta).

Retrieve an authentication token

Retrieving an authentication token requires the use of the User Service Controller API.

An example request showing logging in to the NA region and retrieving the authorization token:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!"
}'

Base URL

The base URL depends on the region that the organization is located in:

Headers

These headers are required:

Body parameters

These required parameters are passed in the body of the request:

Response body

The returned response body contains a list of the organizations that the user is associated with in addition to the authentication token ("authenticationToken"). This token is required for subsequent authorization with the API Manager Log Service API (Beta). In this example, the authentication token is "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4". The organization ID is shown as "123456" for the first organization that this user belongs to. An example of the response:

{
  "status": true,
  "operation": "User login",
  "authenticationToken": "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4",
  "serverUrl": "https://na-east.jitterbit.com",
  "cloudAppsUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [
    {
      "orgId": "123456",
      "orgName": "JB Example Company",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    },
    {
      "orgId": "20970",
      "orgName": "example@jbexample.com",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    }
  ],
  "defaultOrgId": "123456",
  "sessionTimeoutInSeconds": 14400
}

Retrieve an authentication token with TFA enabled

If a user's Harmony organization has two-factor authentication (TFA) enabled, retrieving the authentication token requires two requests using the User Service Controller API:

1. Retrieve a TFA code

2. Use the TFA code to retrieve an authentication token

Retrieve a TFA code

A valid TFA code is required to retrieve an authentication token when TFA is enabled. An example request showing logging in to the NA region and requesting a TFA code:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!",
    "deviceId": "abcd"
}'

Base URL

The base URL depends on the region that the organization is located in:

Headers

These headers are required:

Body parameters

These required parameters are passed in the body of the request:

Response body

The returned response body contains an error message indicating that a TFA code was sent to the user's email address.

{
  "status": false,
  "operation": "User login",
  "errorCode": "VALIDATE_TFA_LOGIN_EMAIL",
  "errorMessage": "Validate your login with authentication code. An email from Jitterbit with the code was sent to you.",
  "authenticationToken": null,
  "serverUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [],
  "defaultOrgId": null
}

Use the TFA code to retrieve an authentication token

The TFA code sent to the user's email address can now be used in the second request to retrieve the authentication token. An example request showing logging in to the NA region with a TFA code and retrieving the authorization token:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login/tfacode' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!",
    "code": "112233",
    "deviceId": "abcd"
}'

Base URL

The base URL depends on the region that the organization is located in:

Headers

These headers are required:

Body parameters

These required parameters are passed in the body of the request:

Response body

The returned response body contains a list of the organizations that the user is associated with in addition to the authentication token ("authenticationToken"). This token is required for subsequent authorization with the API Manager Log Service API (Beta). In this example, the authentication token is "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4". The organization ID is shown as "123456" for the first organization that this user belongs to. An example of the response:

{
  "status": true,
  "operation": "User login",
  "authenticationToken": "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4",
  "serverUrl": "https://na-east.jitterbit.com",
  "cloudAppsUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [
    {
      "orgId": "123456",
      "orgName": "JB Example Company",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    },
    {
      "orgId": "654321",
      "orgName": "example@jbexample.com",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    }
  ],
  "defaultOrgId": "123456",
  "sessionTimeoutInSeconds": 14400
}

Retrieve API logs asynchronously (Beta)

Once you have the authentication token and the organization ID, you can retrieve API logs asynchronously using the API Manager Log Service API (Beta). An example showing retrieving all records from January 20, 2023 to January 20, 2024:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/api/analytics/debuglogs-async' \
--header 'Content-Type: application/json' --header 'Accept: application/json' --header 'authToken: 1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4' \
--data-raw '{
    "ascendSort": false,
    "retrieveLogMessages": false,
    "timeRangeFrom": "01/20/2023 01:01:00 +0100",
    "timeRangeTo": "01/20/2024 01:01:00 +0100",
    "clientTimeZone": "Europe/Berlin",
    "queryString": "responsetime>5; sourceip=14.141%",
    "orgId": "123456",
    "csvFormat": true
}'

Base URL

The base URL depends on the region that the organization is located in:

Headers

These headers can be used in the request:

Body parameters

These parameters can be passed in the body of the request:

Response body

If successful, the returned response body contains a reference key for tracking and downloading the API log file based on the supplied parameters:

{
    "key": "debug-log-E8D47FE1F172D3EE46C620791E614B78D111CE624485D2E1B3D482370690DC40",
    "status": "COMPLETE"
}

The reference key can then be supplied as part of the following API call to check on the log file's status or to download it if the status is COMPLETE:

curl --location --request GET 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/api/analytics/log-async/{orgId}/{key}' \
--header 'Content-Type: application/json' --header 'Accept: application/json' --header 'authToken: 1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4'

Possible statuses include:

• RECEIVED: Harmony received a valid request to generate the log file. The status will transition to PROCESSING when the request is being executed.
• PROCESSING: The log file is being generated. The status will transition to COMPLETE when the file generation is complete.
• COMPLETE: The log file is ready to be downloaded using the log-async API above.
• INVALID: The reference key could not be found. This status is only reported if an unknown or malformed reference key is supplied to the log-async API.
• ERROR: The reference key was found after the API finished trying to generate the log file, but an error was reported. An error message will also be returned detailing why the generation failed.
• NO_DATA: The filtering parameters querying data in the original API call returned 0 results.