Apple Business Manager

@dougschaefer/apple-business-managerv2026.08.10.1· 11d agoMODELS

01README

Read and administer an Apple Business Manager organization over the Apple Business API. OAuth 2 client-credentials auth with an ES256 JWT client assertion signed in WebCrypto — no JWT library, no native dependencies — with in-process token caching, 429 and 5xx retry honouring Retry-After, and automatic re-mint on a mid-flight 401. Accepts the private key whether it is PKCS#8 or SEC1, detected from the DER rather than the PEM label, because Apple issues a PKCS#8 key under EC PRIVATE KEY armour. Roll the whole organization up in one call — devices tallied by product family, status, and purchase source alongside the device management service inventory. Sweep devices, device management services, blueprints, configurations, users, user groups, organizational units, apps, and packages, each fully paged through links.next and filterable client-side with a CEL selector since the API offers no server-side filtering. Drill into a single device, its AppleCare coverage, its assigned management service, or an enrolled device's OS, storage, FileVault, firewall, lock, and erase state. Assign and unassign devices to a device management service as one batched activity and poll it to completion, read the organization audit log over a time window, and reach any unwrapped endpoint through an authenticated passthrough. Works against Apple School Manager by pointing apiBaseUrl at api-school.apple.com and setting the scope to school.api.

02Release Notes

First registry publish of the Apple Business Manager model over the Apple Business API.

03Models1

@dougschaefer/apple-business-managerv2026.08.10.1apple-business-manager/apple-business-manager.ts

fn testConnection()

Mint an access token and read one device, proving the credentials and the API account's role both work. Deliberately a method rather than a pre-flight check: checks run ahead of every method, and on a cold cache this is the call that spends a token mint — the scarcest thing in this API. Run it when you want to prove connectivity, not on every operation.

fn sync(maxPages: number, limit: number)

Roll up the whole organization in one call — every device tallied by product family, status, and purchase source, alongside the device management service inventory and their device counts. The cheapest way to see fleet shape and spot devices sitting unassigned.

Argument	Type	Required	Description
maxPages	number	yes	Page ceiling while sweeping devices
limit	number	yes	Devices per page while sweeping

fn listDevices(limit: number, maxPages: number, fields: string, selector: string)

List every device the organization owns, with serial number, model, product family, purchase source, MAC addresses, and assignment status. Use `selector` to narrow — the Apple collection accepts no server-side filters.

Argument	Type	Required	Description
limit	number	yes	Records per page. Apple defaults to 100 and caps most collections at 1000
maxPages	number	yes	Page ceiling, so a large organization can't run unbounded
fields	string	yes	Comma-separated attribute names to return instead of the full record, e.g. serialNumber,productFamily,status
selector	string	yes	Optional CEL predicate filtered client-side over each flattened record, e.g. productFamily == "Mac" && status == "UNASSIGNED". Apple\

fn getDevice(deviceId: string, fields: string)

Read one device by its Apple Business Manager device ID (for organization devices this is the serial number).

Argument	Type	Required	Description
deviceId	string	yes	Device ID / serial number
fields	string	yes	Comma-separated attribute names to return instead of the full record

fn getDeviceCoverage(deviceId: string, limit: number)

Read AppleCare coverage for one device — plan, status, payment type, and coverage dates. Useful for warranty reporting across a deployed fleet.

Argument	Type	Required	Description
deviceId	string	yes	Device ID / serial number
limit	number	yes

fn getAssignedService(deviceId: string)

Read the device management service a device is currently assigned to, returning the full service record rather than just its ID.

Argument	Type	Required	Description
deviceId	string	yes	Device ID / serial number

fn listMdmServices(limit: number, maxPages: number, fields: string, selector: string)

List the organization's device management services — MDM servers, Apple Configurator instances, and Apple's own MDM — with device counts, last check-in time, and last connected IP.

Argument	Type	Required	Description
limit	number	yes	Records per page. Apple defaults to 100 and caps most collections at 1000
maxPages	number	yes	Page ceiling, so a large organization can't run unbounded
fields	string	yes	Comma-separated attribute names to return instead of the full record, e.g. serialNumber,productFamily,status
selector	string	yes	Optional CEL predicate filtered client-side over each flattened record, e.g. productFamily == "Mac" && status == "UNASSIGNED". Apple\

fn getMdmService(mdmServerId: string)

Read one device management service by ID.

Argument	Type	Required	Description
mdmServerId	string	yes	Device management service ID

fn listMdmServiceDevices(mdmServerId: string, limit: number, maxPages: number)

List the device IDs currently assigned to one device management service. Returns linkage records, so pair it with listDevices when you need full device attributes.

Argument	Type	Required	Description
mdmServerId	string	yes	Device management service ID
limit	number	yes
maxPages	number	yes

fn assignDevices(mdmServerId: string, deviceIds: array)

Assign devices to a device management service. Apple queues this asynchronously and returns an activity ID — poll it with getActivity. Reversible with unassignDevices.

Argument	Type	Required	Description
mdmServerId	string	yes	Device management service to assign the devices to
deviceIds	array	yes	Device IDs / serial numbers to assign

fn unassignDevices(mdmServerId: string, deviceIds: array)

Unassign devices from a device management service, returning them to the unassigned pool. Asynchronous like assignDevices — poll the returned activity ID with getActivity.

Argument	Type	Required	Description
mdmServerId	string	yes	Device management service to unassign the devices from
deviceIds	array	yes	Device IDs / serial numbers to unassign

fn getActivity(activityId: string)

Read an assign or unassign activity by ID to see whether it completed. When Apple finishes processing, the record carries a presigned downloadUrl for the per-device CSV result log.

Argument	Type	Required	Description
activityId	string	yes	Activity ID returned by assignDevices or unassignDevices

fn listEnrolledDevices(limit: number, maxPages: number, fields: string, selector: string)

List devices enrolled in Apple's own device management service. Distinct from listDevices, which covers everything the organization owns regardless of who manages it.

Argument	Type	Required	Description
limit	number	yes	Records per page. Apple defaults to 100 and caps most collections at 1000
maxPages	number	yes	Page ceiling, so a large organization can't run unbounded
fields	string	yes	Comma-separated attribute names to return instead of the full record, e.g. serialNumber,productFamily,status
selector	string	yes	Optional CEL predicate filtered client-side over each flattened record, e.g. productFamily == "Mac" && status == "UNASSIGNED". Apple\

fn getEnrolledDeviceDetail(deviceId: string, fields: string)

Read hardware and posture detail for a device enrolled in Apple's device management service — OS version, storage, last check-in, FileVault and firewall state, lock and erase status.

Argument	Type	Required	Description
deviceId	string	yes	Enrolled device ID
fields	string	yes

fn listBlueprints(limit: number, maxPages: number, fields: string, selector: string)

List declarative device configuration blueprints, with status and whether app licences are short for the devices assigned.

Argument	Type	Required	Description
limit	number	yes	Records per page. Apple defaults to 100 and caps most collections at 1000
maxPages	number	yes	Page ceiling, so a large organization can't run unbounded
fields	string	yes	Comma-separated attribute names to return instead of the full record, e.g. serialNumber,productFamily,status
selector	string	yes	Optional CEL predicate filtered client-side over each flattened record, e.g. productFamily == "Mac" && status == "UNASSIGNED". Apple\

fn listConfigurations(limit: number, maxPages: number, fields: string, selector: string)

List the settings payloads that blueprints reference, by type and platform.

Argument	Type	Required	Description
limit	number	yes	Records per page. Apple defaults to 100 and caps most collections at 1000
maxPages	number	yes	Page ceiling, so a large organization can't run unbounded
fields	string	yes	Comma-separated attribute names to return instead of the full record, e.g. serialNumber,productFamily,status
selector	string	yes	Optional CEL predicate filtered client-side over each flattened record, e.g. productFamily == "Mac" && status == "UNASSIGNED". Apple\

fn listUsers(limit: number, maxPages: number, fields: string, selector: string)

List managed Apple Accounts in the organization, with status, role and organizational-unit mappings, and directory attributes. Needs an API account role that covers people management.

Argument	Type	Required	Description
limit	number	yes	Records per page. Apple defaults to 100 and caps most collections at 1000
maxPages	number	yes	Page ceiling, so a large organization can't run unbounded
fields	string	yes	Comma-separated attribute names to return instead of the full record, e.g. serialNumber,productFamily,status
selector	string	yes	Optional CEL predicate filtered client-side over each flattened record, e.g. productFamily == "Mac" && status == "UNASSIGNED". Apple\

fn listUserGroups(limit: number, maxPages: number, fields: string, selector: string)

List user groups, with type and status.

Argument	Type	Required	Description
limit	number	yes	Records per page. Apple defaults to 100 and caps most collections at 1000
maxPages	number	yes	Page ceiling, so a large organization can't run unbounded
fields	string	yes	Comma-separated attribute names to return instead of the full record, e.g. serialNumber,productFamily,status
selector	string	yes	Optional CEL predicate filtered client-side over each flattened record, e.g. productFamily == "Mac" && status == "UNASSIGNED". Apple\

fn listOrganizationalUnits(limit: number, maxPages: number, fields: string, selector: string)

List organizational units — the locations and sites that scope roles and device assignment.

Argument	Type	Required	Description
limit	number	yes	Records per page. Apple defaults to 100 and caps most collections at 1000
maxPages	number	yes	Page ceiling, so a large organization can't run unbounded
fields	string	yes	Comma-separated attribute names to return instead of the full record, e.g. serialNumber,productFamily,status
selector	string	yes	Optional CEL predicate filtered client-side over each flattened record, e.g. productFamily == "Mac" && status == "UNASSIGNED". Apple\

fn listApps(limit: number, maxPages: number, fields: string, selector: string)

List apps available to the organization through Apps and Books.

Argument	Type	Required	Description
limit	number	yes	Records per page. Apple defaults to 100 and caps most collections at 1000
maxPages	number	yes	Page ceiling, so a large organization can't run unbounded
fields	string	yes	Comma-separated attribute names to return instead of the full record, e.g. serialNumber,productFamily,status
selector	string	yes	Optional CEL predicate filtered client-side over each flattened record, e.g. productFamily == "Mac" && status == "UNASSIGNED". Apple\

fn listPackages(limit: number, maxPages: number, fields: string, selector: string)

List packages available to the organization.

Argument	Type	Required	Description
limit	number	yes	Records per page. Apple defaults to 100 and caps most collections at 1000
maxPages	number	yes	Page ceiling, so a large organization can't run unbounded
fields	string	yes	Comma-separated attribute names to return instead of the full record, e.g. serialNumber,productFamily,status
selector	string	yes	Optional CEL predicate filtered client-side over each flattened record, e.g. productFamily == "Mac" && status == "UNASSIGNED". Apple\

fn auditEvents(startTimestamp: string, endTimestamp: string, days: number, eventType: string, actorId: string, subjectId: string, limit: number, maxPages: number)

Read the organization audit log for a time window — devices added, released, assigned and unassigned, account and role changes, domain changes, and API account key events. Apple requires both window bounds and pages this collection by cursor.

Argument	Type	Required	Description
startTimestamp	string	yes	ISO-8601 window start. Defaults to `days` ago when left empty
endTimestamp	string	yes	ISO-8601 window end. Defaults to now when left empty
days	number	yes	Window size used when startTimestamp is empty
eventType	string	yes	Optional filter[type] value, e.g. DEVICE_ASSIGNED_TO_SERVER
actorId	string	yes	Optional filter[actorId]
subjectId	string	yes	Optional filter[subjectId]
limit	number	yes
maxPages	number	yes

fn request(method: enum, path: string, query: string, body: string)

Authenticated passthrough to any Apple Business API path, for endpoints this model does not wrap yet. Handles token minting, retries, and error decoding; you supply the method, path, and optional body.

Argument	Type	Required	Description
method	enum	yes
path	string	yes	API-relative path beginning with /v1, e.g. /v1/blueprints/ABC/relationships/apps
query	string	yes	Optional query string, e.g. limit=200&fields[apps]=name
body	string	yes	Optional JSON request body as a string

Resources

org(30d)— Organization rollup — device totals by product family, status, and purchase source, plus device management service inventory

collection(30d)— A list of one kind of Apple Business object (devices, device management services, blueprints, configurations, users, user groups, organizational units, apps, packages)

detail(30d)— Single-object drill-down (one device, its AppleCare coverage, its assigned device management service, one management service, or one enrolled device's hardware detail)

activity(90d)— An assign or unassign device activity — Apple processes these asynchronously, so status and subStatus advance after creation

auditEvents(90d)— A window of the organization audit log, covering device, account, domain, subscription, and API-account events

response(7d)— Raw response from the generic authenticated passthrough

04Stats

100 / 100

Downloads

Archive size

35.1 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License declared1/1earned
Verified public repository2/2earned

Repository

https://github.com/dougschaefer6/swamp-apple-business-manager

05Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64

06Labels

#apple #apple-business-manager #apple-school-manager #mdm #device-management #macos #ios #fleet-management #rest