Classic API Overview
Introduction
The Classic API is primary tool for programmatic access to data within the system and to allow for integrations with other systems. The base URL for the Classic API is located at /JSSResource
on each Jamf Pro instance. Documentation and “Try it out” features are built into each instance of Jamf Pro, and can be accessed at /api
.
Authentication and Authorization
Notice
API authentication does not support the use of SSO. See SSO documentation for more information on places where SSO is supported with Jamf Pro.
Client Credentials
Beginning in version 10.49.0, support for Client Credentials authentication was introduced for the Jamf Pro and Classic APIs. See Client Credentials for additional details.
Bearer Tokens
Beginning in version 10.35.0, support for Bearer Token authentication was added to the Classic API. Support for Bearer token authentication is accompanied by the deprecation notice of Basic authentication in the Classic API with removal of support occurring March of 2024. For more information regarding these changes, please see Classic API Authentication Changes.
Need a little help getting started with Bearer Tokens? We've got you covered, with an example code snippet:
The Classic API uses the standard User Accounts and Groups functionality of Jamf Pro. The Create, Read, Update and Delete privileges for an account or group within Jamf Pro correspond respectively with the POST, GET, PUT and DELETE HTTP methods. Furthermore, the Jamf Pro Server Object or Jamf Pro Server Setting should closely describe the endpoint for which permissions would be granted (e.g privileges for Advanced Computer Searches would be required to interact with the advancedcomputersearches
endpoint). For more information see Privilege Requirements.
HTTP Methods
The Classic API is a RESTful interface that uses standard HTTP methods to issue requests and receive responses.
POST is used to create new objects or issue new actions. Most POST operations require that an XML body be passed with the request, however some endpoints support only path parameters. When an XML body is required, Jamf recommends setting the {id}
path parameter to 0. (e.g. /JSSResource/endpointname/id/0
). Jamf Pro auto-assigns the object an ID and will respond to successful requests with the ID of the created resource.
GET is used to retrieve information identified by the request-URI. Many endpoints support a {subset}
path parameter, which tells the sever to return only certain subsets of information. Each endpoint supports a different array of subset values, which can be viewed by clicking the “Try it out” button for that specific endpoint within the API Reference page.
PUT is used to update existing records, identified by the request-URI. In most cases PUT will only update the fields specified within the XML body and will leave values for fields not specified within the XML body as their previously defined values. Responses to successful requests will include the ID of the updated resource.
DELETE is used to remove the resource identified by the request-URI. If successful the message response should include the ID of the deleted resource.
Schema
The Classic API is capable of producing XML and JSON format responses for GET type requests to the API. The API is limited to XML data formats for PUT and POST type requests. Jamf recommends including an Accept header Accept: application/json
or Accept: text/xml
to define the content type expected by the client. Please see Application Header Best Practices for additional details.
Response Codes
The Classic API returns standard HTTP status codes for both successful and unsuccessful API calls. All errors returned will include an HTML response that contains a description of the failure.
Common response codes and steps to troubleshoot failures.
Code | Description |
---|---|
200 | Request successful. |
201 | Request to create or update object successful. |
400 | Bad request. Verify the syntax of the request specifically the XML body. |
401 | Authentication failed. Verify the credentials being used for the request. |
403 | Invalid permissions. Verify the account being used has the proper privileges for the resource you are trying to access. |
404 | Resource not found. Verify the URI path is correct. |
409 | Conflict. See the error response for additional details. |
500 | Internal server error. Retry the request or contact Jamf support if the error is persistent. |
502 | Bad Gateway. Generally due to a timeout issue. |
Updated 8 months ago