Getting Started

Install

Install the SDK from PyPI. The example is shown with your virtual environment active.

(.venv) % python -m pip install jamf-pro-sdk

Install Locally

Install locally into your virtual environment. You must first clone the SDK repository. The example is shown with your virtual environment active.

(.venv) % python -m pip install /path/to/jamf-pro-sdk-python

When running pip freeze the SDK will appear with a filepath to the source instead of the version.

(.venv) % pip freeze
...
jamf-pro-sdk @ file:///path/to/jamf-pro-sdk-python
...

Create a Client

Import the Jamf Pro client from the SDK:

>>> from jamf_pro_sdk import JamfProClient, BasicAuthProvider

Create a client object passing in your Jamf Pro server name and a username and password:

Note

When passing your Jamf Pro server name, do not include the scheme (https://) as the SDK handles this automatically for you.

>>> client = JamfProClient(
...     server="jamf.my.org",
...     credentials=BasicAuthProvider("oscar", "j@mf1234!")
... )
>>>

The BasicAuthProvider is a credentials provider. These objects are interfaces for authenticating for access tokens to the Jamf Pro APIs. Basic auth credentials providers use a username and password for authentication when requesting a new token.

To use an API Client for authentication (Jamf Pro 10.49+) use ApiClientCredentialsProvider.

There are a number of built-in Credentials Providers available. To learn how to implement your own visit Custom Credentials Providers.

Important

Do not plaintext secrets (passwords, clients secrets, etc.) in scripts or the console. The use of the base BasicAuthProvider class in this guide is for demonstration purposes.

On the first request made the client will retrieve and cache an access token. This token will be used for all requests up until it nears expiration. At that point the client will refresh the token. If the token has expired the client will basic auth for a new one.

You can retrieve the current token at any time:

>>> access_token = client.get_access_token()
>>> access_token
AccessToken(type='user', token='eyJhbGciOiJIUzI1NiJ9...', expires=datetime.datetime(2023, 8, 21, 16, 57, 1, 113000, tzinfo=datetime.timezone.utc), scope=None)
>>> access_token.token
'eyJhbGciOiJIUzI1NiJ9.eyJhdXRoZW50aWNhdGVkLWFwcCI6IkdFTkVSSUMiLCJhdXRoZW50aWNhdGlvbi10eXBlIjoiSlNTIiwiZ3JvdXBzIjpbXSwic3ViamVjdC10eXBlIjoiSlNTX1VTRVJfSUQiLCJ0b2tlbi11dWlkIjoiM2Y4YzhmY2MtN2U1Ny00Njg5LThiOTItY2UzMTIxYjVlYTY5IiwibGRhcC1zZXJ2ZXItaWQiOi0xLCJzdWIiOiIyIiwiZXhwIjoxNTk1NDIxMDAwfQ.6T9VLA0ABoFO9cqGfp3vWmqllsp3zAbtIW0-M-M41-E'
>>>

Both the Classic and Pro APIs are exposed through two interfaces:

>>> client.classic_api
<jamf_pro_sdk.clients.classic_api.ClassicApi object at 0x10503d240>
>>> client.pro_api
<jamf_pro_sdk.clients.pro_api.ProApi object at 0x10503c9d0>
>>>

Continue on to Classic API or the Pro API.

Configuring the Client

Some aspects of the Jamf Pro client can be configured at instantiation. These include TLS verification, request timeouts, retries, and pool sizes. Below is the SessionConfig object used to customize these settings:

pydantic model SessionConfig

Jamf Pro client session configuration.

Parameters:

  • timeout (int) – HTTP request timeout (defaults to no timeout set).

  • max_retries (int) – HTTP request retries (defaults to 0).

  • max_concurrency (int) – The maximum number of HTTP connections the client will create when making concurrent requests (defaults to 5).

  • return_exceptions – Global setting that controls returning exceptions when concurrent_operations() is invoked. Setting this to True will return the exception object if an error is encountered by the handler. If False no response will be given for that operation.

  • user_agent (str) – Override the default User-Agent string included with SDK requests.

  • verify (bool) – TLS certificate verification (defaults to True).

  • cookie (str | Path) – A path to a text cookie file to attach to the client session.

  • ca_cert_bundle (str | Path) – A path to a CA cert bundle to use in addition to the system trust store.

  • scheme (str) – Override the URL scheme to http (defaults to https). It is strongly advised that you use HTTPS for certificate verification.

Note

The max_concurrency setting is used with the SDK’s concurrency features. Those are covered in Performing Concurrent Operations.

The Jamf Developer Guide states in scalability best practices to not exceed 5 concurrent connections. Read more about scalability with the Jamf Pro APIs here.

The Jamf Pro client will create a default configuration if one is not provided.

>>> from jamf_pro_sdk import JamfProClient, BasicAuthProvider, SessionConfig
>>> config = SessionConfig()
>>> config
SessionConfig(timeout=None, max_retries=0, max_concurrency=5, verify=True, cookie=None, ca_cert_bundle=None, scheme='https')
>>>

Here are two examples on how to use a SessionConfig with the client to disable TLS verification and set a 30 second timeout:

>>> config = SessionConfig()
>>> config.verify = False
>>> config.timeout = 30
>>> config
SessionConfig(timeout=30, max_retries=0, max_concurrency=5, verify=False, cookie=None, ca_cert_bundle=None, scheme='https')
>>> client = JamfProClient(
...     server="jamf.my.org",
...     credentials=BasicAuthProvider("oscar", "j@mf1234!")
...     session_config=config,
... )
>>>

>>> config = SessionConfig(**{"verify": False, "timeout": 30})
>>> config
SessionConfig(timeout=30, max_retries=0, max_concurrency=5, verify=False, cookie=None, ca_cert_bundle=None, scheme='https')
>>> client = JamfProClient(
...     server="jamf.my.org",
...     credentials=BasicAuthProvider("oscar", "j@mf1234!")
...     session_config=config,
... )
>>>

Warning

It is strongly recommended you do not disable TLS certificate verification.

Logging

You can quickly setup console logging using the provided logger_quick_setup() function.

>>> import logging
>>> from jamf_pro_sdk.helpers import logger_quick_setup
>>> logger_quick_setup(level=logging.DEBUG)

When set to DEBUG the stream handler and level will also be applied to urllib3’s logger. All logs will appear

If you require different handlers or formatting you may configure the SDK’s logger manually.

>>> import logging
>>> sdk_logger = logging.getLogger("jamf_pro_sdk")