Apple's Business Manager API does the work; its roles model is what breaks deployments

Apple used this year's WWDC to announce an expanded Apple Business API that lets IT admins retrieve device information, review audit events, and assign or unassign devices directly through the API ^[3]. The endpoints are what large fleets have asked for; the part generating friction is the permission model behind them, which developers have reported is frustrating to configure properly ^[1].

The failure mode is specific and repeatable. According to 9to5Mac's Apple @ Work column, written by Bradley Chambers, an Apple IT admin since 2009 ^[12], testers calling the Audit Events API are likely to get a 403 Forbidden, with a message stating that the API key in use does not allow the request ^[2]. The call is not malformed. The API account simply lacks the permission. Apple's documentation does say, in its data access section, that you need permission to access audit events via the Admin API, but per the same report it is not clear how to apply that permission to your account ^[4]. That is the whole gap: a documented requirement with an undocumented path.

The fix lives in Settings > Roles and Permissions, where you adjust the permissions on the API account, and where a custom role can be based on an existing role with permissions added rather than built from nothing ^[5]. The default roles are IT Administrator, Marketing Administrator, People Manager, Device Enrollment Manager, and Content Manager ^[6], five in total ^[13], and checking every individual organization permission attached to each one is tedious ^[7].

Two ceilings deserve attention before anyone writes automation against this. An organization can have up to 50 API accounts and create up to 15 custom roles ^[8]. That works out to roughly 3.3 API accounts per custom role if all fifteen are used ^[14], so one bespoke least-privilege role per integration is not on the table; roles will be shared across accounts, and that mapping is a design decision rather than something to discover later. The second is a governance detail with wider blast radius: any user who can view, edit, and delete roles can change specific permissions for all default roles ^[9]. The meaning of IT Administrator in a given tenant is therefore mutable, and one edit reaches everyone holding it.

The documentation gap is currently being filled from outside Apple. AppleShare IT built a web tool, the Apple Business Roles Checker, using Claude to turn Apple's large default roles and permissions document into a wizard-style checklist ^[10]. An admin selects the organization permissions the API account needs, and the tool identifies which default role already covers them, or shows how to customize an existing role if none does ^[11].

Worth watching: whether Apple documents the path from the stated audit-events requirement to an actual API account configuration ^[4], since every day it does not is a day the community tool is load-bearing infrastructure for other people's deployments ^[10]. Also worth watching is whether the 50-account and 15-custom-role limits hold as more automation moves onto this API ^[8], and whether editing default roles globally ^[9] starts showing up in audit findings rather than support threads.