jamfplatform

Documentation

Overview

Package jamfplatform provides a Go client for the Jamf Platform API.

Create a root client with NewClient, then construct service clients from the sub-packages under jamfplatform/ (devices, devicegroups, deviceactions, blueprints, ddmreport, compliancebenchmarks, pro, ...) to call typed methods.

c := jamfplatform.NewClient(
	"https://your-tenant.apigw.jamf.com",
	os.Getenv("JAMFPLATFORM_CLIENT_ID"),
	os.Getenv("JAMFPLATFORM_CLIENT_SECRET"),
	jamfplatform.WithTenantID(os.Getenv("JAMFPLATFORM_TENANT_ID")),
)

ds, err := devices.New(c).ListDevices(ctx, nil, "")

The root client handles OAuth2 authentication and token refresh automatically; each sub-package shares the same transport via its [New] constructor.

Error handling uses *APIResponseError for structured API errors:

d, err := devices.New(c).GetDevice(ctx, id)
if errors.As(err, &apiErr) && apiErr.HasStatus(404) {
	// handle not found
}

Response headers

Generated methods return the decoded body only. Response headers — including Location on 201 Created, Retry-After on 429 (which the transport already honors with a bounded single retry), and Deprecation on soon-to-be-removed endpoints (logged automatically) — are available to consumers via the WithLogger option. Install a Logger whose LogResponse receives http.Header if you need to inspect Location or any other per-request header.

Note that the body returned by create endpoints already carries an "href" field pointing at the new resource, equivalent to Location.

Index

• Variables
• func PollUntil(ctx context.Context, interval time.Duration, ...) error
• type APIResponseError
  • func AsAPIError(err error) *APIResponseError
• type AmbiguousMatchError
• type Client
  • func NewClient(baseURL, clientID, clientSecret string, opts ...Option) *Client
  • func (c *Client) AccessToken(ctx context.Context) (*oauth2.Token, error)
  • func (c *Client) BaseURL() string
  • func (c *Client) Transport() *client.Transport
  • func (c *Client) ValidateCredentials(ctx context.Context) error
• type ErrorDetail
• type Logger
• type Option
  • func WithFileCookieJar(dir string) Option
  • func WithFileTokenCache(dir string) Option
  • func WithHTTPClient(httpClient *http.Client) Option
  • func WithLogger(logger Logger) Option
  • func WithRetryOn4xx(enabled bool) Option
  • func WithTenantID(id string) Option
  • func WithTokenCache(cache TokenCache) Option
  • func WithUserAgent(userAgent string) Option
• type RSQLClause
• type TokenCache

Variables

var BuildRSQLExpression = client.BuildRSQLExpression

var FormatArgument = client.FormatArgument

Functions

func PollUntil

func PollUntil(ctx context.Context, interval time.Duration, checker func(context.Context) (bool, error)) error

Types

type APIResponseError

type APIResponseError = client.APIResponseError

APIResponseError is returned for any non-success HTTP status. Consumers should inspect it via AsAPIError plus the accessor methods (HasStatus/Details/FieldErrors/Summary) rather than string-matching the Error() output. Non-HTTP errors (denylist refusal, context cancellation, IO failures, etc.) surface as plain wrapped errors — format them with err.Error().

func AsAPIError

func AsAPIError(err error) *APIResponseError

AsAPIError unwraps err and returns the underlying *APIResponseError if present, otherwise nil. Shorthand for errors.As that saves callers from managing the target pointer and importing the concrete error type.

type AmbiguousMatchError

type AmbiguousMatchError = client.AmbiguousMatchError

AmbiguousMatchError is returned by Resolve<Resource>ByName methods when multiple resources share the requested name. Matches carries the IDs of all colliding resources so consumers can surface disambiguation options.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client provides typed methods for all Jamf Platform API operations.

func NewClient

func NewClient(baseURL, clientID, clientSecret string, opts ...Option) *Client

NewClient creates a new Jamf Platform API client.

func (*Client) AccessToken

func (c *Client) AccessToken(ctx context.Context) (*oauth2.Token, error)

AccessToken returns a valid OAuth2 token from the client's credentials configuration.

func (*Client) BaseURL

func (c *Client) BaseURL() string

BaseURL returns the base URL configured for the client.

func (*Client) Transport

func (c *Client) Transport() *client.Transport

Transport returns the underlying transport used by sub-package clients in jamfplatform/. Sub-package constructors (e.g. devices.New) call this to share the authenticated HTTP layer.

func (*Client) ValidateCredentials

func (c *Client) ValidateCredentials(ctx context.Context) error

ValidateCredentials tests authentication by requesting an OAuth token.

type ErrorDetail

type ErrorDetail = client.Error

ErrorDetail is a single structured error entry parsed from an API response body. Consumers receive these via APIResponseError.Details() or APIResponseError.FieldErrors().

type Logger

type Logger interface {
	LogRequest(ctx context.Context, method, url string, body []byte)
	LogResponse(ctx context.Context, statusCode int, headers http.Header, body []byte)
}

type Option

type Option func(*clientConfig)

Option configures a Client.

func WithFileCookieJar

func WithFileCookieJar(dir string) Option

WithFileCookieJar enables file-based cookie jar persistence in the given directory. The cookie jar survives across process invocations so sticky-session cookies keep pointing a CLI-style caller at the same app node between runs.

func WithFileTokenCache

func WithFileTokenCache(dir string) Option

WithFileTokenCache enables file-based token caching in the given directory.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient overrides the default HTTP client.

func WithLogger

func WithLogger(logger Logger) Option

WithLogger sets a logger for HTTP request/response logging.

func WithRetryOn4xx

func WithRetryOn4xx(enabled bool) Option

WithRetryOn4xx opts the client into retrying unexpected 4xx responses (400–499, excluding 401 and 403) with exponential backoff. Intended for API families that exhibit eventual consistency — e.g. a device-group DELETE returning 400 HAS_DEPENDENCIES immediately after the referencing blueprint was deleted. Backoff starts at 2s, caps at 10s; context timeout is the only bound. Default is off.

func WithTenantID

func WithTenantID(id string) Option

WithTenantID configures the tenant ID used to build API URL paths. When set, all API paths include /tenant/{tenantID} in the URL. When not set, legacy internal paths are used.

func WithTokenCache

func WithTokenCache(cache TokenCache) Option

WithTokenCache sets a custom token cache for persisting tokens across process restarts.

func WithUserAgent

func WithUserAgent(userAgent string) Option

WithUserAgent sets a custom user agent string.

type RSQLClause

type RSQLClause = client.RSQLClause

type TokenCache

type TokenCache interface {
	Load(key string) (token string, expiresAt time.Time, ok bool)
	Store(key string, token string, expiresAt time.Time) error
}