JumpCloud Reports API Endpoints Live

[dwjohn]

Hey JumpCloud Community. I am back to share that customers can now access JumpCloud Reports via api in addition to what they could already do in the Admin Console. JumpCloud Reports has been in General Availability for a few weeks and we wanted to fix some of the api responses before officially enabling the api portion. This was something that was highly requested and we know that there is already some interesting automation being developed by customers leveraging the data now available via JumpCloud reports.

Endpoints and Documentation

The api documentation for the JumpCloud Reports focused endpoints can be found in the Reports Section of the JumpCloud Directory Insights API (1.0). In there, you will find the following 3 endpoints:

• Request a Users to Resources report - request a report on users and their associated resources (Devices, Directories, RADIUS Server and LDAP)
• Get a list of report metadata - returns an ordered list of report metadata - including report id, report status, and artifact id to download
• Download a report - download a report by report ID and artifact ID - can select either json or csv artifact to download

Report Generation and Download Pattern

In my previous community post - Introducing JumpCloud Reports, I talked about the Stored Report Queue and the need to have a logical location in the admin console for retrieving longer running reports. This same concept carries over to the api experience in that requesting the report is separate from downloading the report. Reports can take a while to run for a couple of reasons - (1) the size of the organization is so large that it takes time for the query to complete and (2) the traffic of reports running is high and the new report being requested is in the queue.

The standard flow for running a report via api calls is: 

(1) request the report

curl --request POST \
  --url 'https://api.jumpcloud.com/insights/directory/v1/reports/users_to_resources?resource=SOME_STRING_VALUE' \
  --header 'accept: application/json' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

This is only going to kick off the report and the response will reflect that the request has been received successfully or not.

(2) get the report metadata

curl --request GET \
  --url 'https://api.jumpcloud.com/insights/directory/v1/reports?sort=SOME_STRING_VALUE' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

This step will allow for you to see if the report has completed and retrieve both the report id and artifact id (either csv or json).

(3) download the report leveraging the report metadata

curl --request GET \
  --url https://api.jumpcloud.com/insights/directory/v1/reports/{report_id}/artifacts/{artifact_id}/content \
  --header 'x-api-key: REPLACE_KEY_VALUE'

This step will actually download the report that you previously ran.

Automation, Automation, Automation

Now the fun begins!!! We know that the data contained in these reports is more valuable to customers than just the artifact itself. Otherwise, we wouldn’t have received so many requests and interest in this feature. Now that this is available via api, the automation that can be developed around this data is significant. We want to hear your stories. Please come back into the community and share the creative ways that you are using these reports and the data that they contain.