applebusiness 0.2.1

Async Python client for the Apple Business API

applebusiness

Async Python client for the Apple Business API.

Install

pip install applebusiness

Requires Python 3.14+.

Authentication

You need an API key generated in Apple Business Manager. The client uses the OAuth 2.0 client-credentials flow with a JWT client assertion signed by your private key. See Implementing OAuth for the Apple School Manager and Apple Business API.

You'll need:

• key_id — the key identifier from Apple Business Manager
• client_id — your API account's client ID
• private_key_pem — the PEM-encoded EC private key

Usage

import asyncio
from applebusiness import Client

async def main():
    async with Client(key_id, client_id, private_key_pem) as client:
        devices = await client.get_org_devices()
        for device in devices.data:
            print(device.id, device.attributes.serialNumber)

asyncio.run(main())

Token caching

By default, OAuth tokens are cached in memory on the Client instance. To share tokens across processes (e.g. via Redis), subclass Client and override _get_cached_token / _set_cached_token:

class RedisClient(Client):
    async def _get_cached_token(self):
        raw = await redis.get("ab-token")
        return json.loads(raw) if raw else None

    async def _set_cached_token(self, token):
        await redis.set("ab-token", json.dumps(token), ex=token["expires_in"])

Coverage

The client implements every Apple Business API endpoint documented as of this release:

• Devices — get_org_devices, get_org_device, get_org_device_apple_care_coverage, get_mdm_devices, get_mdm_device_details
• Device Management Services — get_mdm_servers, get_mdm_server_device_ids, get_org_device_assigned_server_id, get_org_device_assigned_server, assign_devices_to_server, unassign_devices_from_server, get_org_device_activity
• Users — get_users, get_user
• User Groups — get_user_groups, get_user_group, get_user_group_user_ids
• Apps & Packages — get_apps, get_app, get_packages, get_package
• Blueprints — get_blueprints, create_blueprint, get_blueprint, update_blueprint, delete_blueprint, and get_blueprint_<rel>_ids add_<rel>_to_blueprint / remove_<rel>_from_blueprint for apps, configurations, packages, org_devices, users, user_groups
• Configurations — get_configurations, create_configuration, get_configuration, update_configuration, delete_configuration
• Audit — get_audit_events

All responses are returned as typed Pydantic models (importable from the top-level applebusiness package).

Pagination

List endpoints accept limit and cursor for manual paging. Each response exposes meta.paging.nextCursor — pass it back as cursor to fetch the next page:

page = await client.get_org_devices(limit=100)
while page.meta.paging.nextCursor:
    page = await client.get_org_devices(
        limit=100, cursor=page.meta.paging.nextCursor
    )

To iterate every item across all pages, pass the bound list method to Client.paginate. Extra keyword arguments (e.g. limit, filters) are forwarded on every request:

async for device in client.paginate(client.get_org_devices, limit=200):
    print(device.id)

async for event in client.paginate(
    client.get_audit_events,
    start_timestamp="2026-01-01T00:00:00Z",
    end_timestamp="2026-02-01T00:00:00Z",
):
    ...

Activity polling

assign_devices_to_server and unassign_devices_from_server poll the resulting orgDeviceActivity until it leaves IN_PROGRESS. The polling timeout defaults to 300 seconds and raises TimeoutError when exceeded. To skip polling, pass wait=False; to wait indefinitely, pass timeout=None.

Errors

Non-2xx responses raise applebusiness.ClientError, which exposes the HTTP status and parsed ErrorResponse body.

License

MIT