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).
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.
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.
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.
- Obtain the Network ID from your Jamf School environment by navigating to Devices >> Enroll Device(s).
- Combine the network ID and API key values into a string similar to
- 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.
printf "NetworkID:APIKeyValue" | base64 -I -
- Construct the complete Authorization header by combining the output from the step above with the header information below.
Authorization Basic: Base64EncodedNetworkIDAndAPIKey
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").
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.
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.
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.
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.
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.
Updated over 2 years ago