Jamf School

Learn about the basics of the Jamf School API

Overview

The Jamf School API allows for programmatic access to many of the features available from the Jamf School UI. API Reference documentation can be found here or by appending /api/docs to your Jamf School URL (e.g. https://yourCompany.jamfcloud.com/api/docs).

❗️

Documentation Correction

The API Reference documentation erroneously describes the API endpoint as being accessible from https://api.zuludesk.com/. Jamf has updated its location in the following manner. https://yourSchool.jamfcloud.com/api.

Authorization

Before attempting to access the API, an API key must first be generated from the Jamf School UI. This can be done from the Organization >> Settings >> API tab. Make sure to only include the access rights necessary to perform the actions your tool or application requires. Should the need arise where access rights need to be changed, you can update them in the Edit API Key window.

API key creation screen.API key creation screen.

API key creation screen.

Now that we have an API key, let's explore how to obtain authorization to the API endpoints. All API requests to Jamf School require the use of a Basic Authorization header. Use the steps below to generate an encoded set of credentials for access to API endpoints.

  1. Obtain the Network ID from your Jamf School environment by navigating to Devices >> Enroll Device(s).
Obtain the network ID from the Enroll Device(s) page.Obtain the network ID from the Enroll Device(s) page.

Obtain the network ID from the Enroll Device(s) page.

  1. Combine the network ID and API key values into a string similar to NetworkID:APIKeyValue
  2. Base64 encode the string generated in step 2.
    i. A command similar to the following can be run from Terminal to generate the authorization token.
    ii. printf "NetworkID:APIKeyValue" | base64 -I -
  3. Construct the complete Authorization header by combining the output from the step above with the header information below.
    i. Authorization Basic: Base64EncodedNetworkIDAndAPIKey

Versioning

The Jamf School API uses headers to specify the version of a resource to interact with. The header name used to specify the version is "X-Server-Protocol-Version" where the value should match the version of the endpoint you intend to interact with (e.g. "X-Server-Protocol-Version: 2").

🚧

Important

If no version header is specified, the API defaults to using version 1 of the endpoint. Note, if version 1 of an endpoint does not exist, the request will fail. As a best practice Jamf recommends including the version header and value with all API requests, to ensure your interaction is with the version of the resource you intend to interact with.

Using the API Reference

The Jamf School API Reference defaults to showing documentation for version 3 of all endpoints. At the top of the page, you can select the version of the documentation you'd like to view. Recall from the section above, that without specifying a version header, your requests will all default to using version 1 of an endpoint, while the documentation defaults to displaying the newest version of the endpoint.

Global documentation version selector.Global documentation version selector.

Global documentation version selector.

In addition to the global version selector, each endpoint includes a version selector for the documentation.

Documentation for an endpoint includes a sample URI for accessing the endpoint, which can be found immediately after a description of the endpoint and the HTTP operation used to interact with the endpoint. Additionally, a list of parameters supported by that endpoint are described in a table format as pictured below. For PUT and POST operations, query parameters are described as (Placed in URL) and differ from the other parameters which are used to construct the request body. For GET operations, all parameters should be assumed to be query parameters unless otherwise described.

Depiction of the URI, HTTP operation and supported parameters.Depiction of the URI, HTTP operation and supported parameters.

Depiction of the URI, HTTP operation and supported parameters.

Some endpoints also include sample request bodies which can be used as templates for interacting with the endpoint. This is more common with endpoints that have a complex set of supported parameters and should help formulate a valid request to the API.

Example request body.Example request body.

Example request body.

All endpoints include an example response from the endpoint. Most include examples of both a successful response as well as failure states that may be possible for that endpoint. Click the available tabs to view responses related to the described failure state.

Success and failure responses.Success and failure responses.

Success and failure responses.