apple-business-go

README

apple-business-go

An unofficial Go SDK for Apple Business. A library for calling the Apple Business / School Manager API (api-business.apple.com / api-school.apple.com). It supports OAuth2 (client_credentials + ES256 JWT) authentication, reading devices / users / MDM servers and more, and assigning / unassigning devices (writes).

In April 2026, Apple Business Manager, Apple School Manager, and Apple Business Essentials were unified into a single platform, "Apple Business" (four pillars: device / people / brand / support). This SDK is structured around that umbrella brand, anticipating future pillars (such as brand management).

⚠️ This is an unofficial SDK. The API definitions were extracted and verified from public implementations, but final confirmation against Apple's official documentation is recommended before production use (see docs/apple-business-api-reference.md).

---

Package layout (mapped to the four pillars)

apple-business-go/
├── applebusiness/   Core (shared foundation): Client, Config, Credentials, OAuth2/JWT, transport, pagination, errors
├── devices/         Device management: orgDevices, mdmServers, orgDeviceActivities, appleCareCoverage
├── blueprints/      Blueprint management: CRUD + assignment (apps/configurations/devices/users/groups)
├── configurations/  Configuration management: CRUD (CUSTOM_SETTING profiles)
├── apps/            Apps / packages (read-only): apps, packages
├── auditevents/     Audit events (read-only): auditEvents
├── people/          People management: users, userGroups
├── brand/           Brand management (future / Apple Business Connect)
└── support/         Support (future)

• The service packages (devices / people) accept a *applebusiness.Client and operate on it.
• Authentication, retries, and pagination are centralized in the applebusiness core; the core stays unchanged as pillars are added.

---

Install

go get github.com/hitoshiichikawa/apple-business-go/applebusiness
go get github.com/hitoshiichikawa/apple-business-go/devices

Quickstart (read)

import (
    "github.com/hitoshiichikawa/apple-business-go/applebusiness"
    "github.com/hitoshiichikawa/apple-business-go/devices"
)

pem, _ := os.ReadFile("abm_private_key.pem") // EC P-256 (.pem)

c, err := applebusiness.NewClient(applebusiness.Config{
    BaseURL: applebusiness.DefaultBusinessBaseURL, // use DefaultSchoolBaseURL for ASM
    Credentials: applebusiness.Credentials{
        ClientID:   "BUSINESSAPI.xxxxxxxx-....",
        TeamID:     "BUSINESSAPI.xxxxxxxx-....", // typically identical to client_id on AxM
        KeyID:      "xxxxxxxx-....",
        PrivateKey: pem,
        Scope:      "business.api", // auto-detected from client_id when empty
    },
})

devs, err := devices.New(c).List(context.Background(), nil) // pagination handled automatically
for _, d := range devs {
    fmt.Println(d.Attributes.SerialNumber, d.Attributes.Status)
}

Quickstart (write: assign / unassign)

svc := devices.New(c)
act, err := svc.Assign(ctx, serverID, []string{deviceID1, deviceID2})
// to unassign: svc.Unassign(ctx, serverID, deviceIDs)

final, err := svc.PollActivity(ctx, act.ID, 3*time.Second)
fmt.Println(final.Attributes.Status, final.Attributes.SubStatus)

Runnable samples live in examples/ (list-devices, assign-devices, smoke-test, dump-all, write-test). For a connectivity check use smoke-test; to dump every read endpoint use dump-all.

Quickstart (audit events)

// /v1/auditEvents requires filter[startTimestamp]; use ListRange for a time range
events, _ := auditevents.New(c).ListRange(ctx, time.Now().AddDate(0, 0, -7), time.Now(), nil)
for _, ev := range events {
    a := ev.Attributes // common fields: a.Type, a.ActorID, a.EventDateTime ...
    if a.Type == "DEVICE_ASSIGNED_TO_SERVER" {
        var d auditevents.DeviceAssignedToServer
        _ = a.Payload(&d) // d.SerialNumber, d.TargetServerName
    }
}

---

Authentication

Issue credentials in the Apple Business / School Manager portal (Organization Administrator only).

Item	Description
client_id	e.g. BUSINESSAPI.<uuid>
key_id	the kid in the JWT header
team_id	issuer (typically identical to client_id on AxM)
private key	.pem (EC P-256 / for ES256)

Generate a JWT client assertion signed with ES256 and exchange it at POST https://account.apple.com/auth/oauth2/token with grant_type=client_credentials. The scope is business.api / school.api. Access tokens are valid for one hour.

---

Supported endpoints

Package	Methods	API
devices	List / Get	/v1/orgDevices, /v1/orgDevices/{id}
devices	AssignedServer / AppleCareCoverage	/v1/orgDevices/{id}/assignedServer, .../appleCareCoverage
devices	ListMdmServers / MdmServerDevices	/v1/mdmServers, /v1/mdmServers/{id}/relationships/devices
devices	Assign / Unassign / GetActivity / PollActivity	/v1/orgDeviceActivities(/{id})
people	ListUsers / GetUser	/v1/users, /v1/users/{id}
people	ListUserGroups / GetUserGroup / GroupMembers	/v1/userGroups(/{id})(/relationships/users)
blueprints	List / Get / Create / Update / Delete / AddTo / RemoveFrom / Replace / RelationshipIDs	/v1/blueprints(/{id})(/relationships/{rel})
configurations	List / Get / Create / Update / Delete	/v1/configurations(/{id})
apps	ListApps / GetApp / ListPackages / GetPackage	/v1/apps(/{id}), /v1/packages(/{id})
auditevents	List / ListRange	/v1/auditEvents (requires filter[startTimestamp])

The primary source for fields and enum values is docs/apple-business-api-datatypes.md; endpoint details are in docs/apple-business-api-reference.md.

---

Status / roadmap

• Core (OAuth2 / retries / pagination)
• devices (read + assign/unassign)
• people (users / userGroups)
• apps (apps / packages) / auditevents (auditEvents): implemented (read-only); fields match the official spec
• blueprints / configurations (built-in device management): implemented (CRUD + assignment); spec confirmed and write paths verified against the live API
• All resource Attributes, enum values, and the audit model confirmed against the official DocC (docs/apple-business-api-datatypes.md)
• Functional options (WithBaseURL/WithTokenURL/WithMaxRetries/WithUserAgent/WithHTTPClient)
• Typed error predicates (IsNotFound/IsRateLimited/IsUnauthorized/IsForbidden/IsConflict)
• ListSeq (lazy paging via Go 1.23 range-over-func)
• Unit tests (httptest) for all packages / CHANGELOG / golangci-lint / CI (gofmt, vet, build, test -race, lint)
• Idempotency review of write retries (avoid duplicate POSTs)
• brand / support packages (future; brand has no public API spec yet — see ROADMAP.md)

---

Development

Go 1.23+ (uses ListSeq's range-over-func).

go mod tidy
go build ./...
go vet ./...
gofmt -l .              # confirm no diff
golangci-lint run ./...
go test -race ./...

---

Credits

The API definitions and authentication flow were implemented independently, with reference to the following public projects (no code was copied directly):

• micromdm/nanoaxm (Go)
• neilmartin83/terraform-provider-axm (Go)
• and others such as rodchristiansen/asbmutil (Swift), EUCTechTopics/PSABM (PowerShell)

License

MIT. Apple, Apple Business, Apple Business Manager, and Apple School Manager are trademarks of Apple Inc. This is an unofficial project, not affiliated with Apple.