Skip to main content

​
About Apple Business Manager

Apple Business Manager (ABM) is Apple’s portal for IT administrators to deploy and manage Apple devices, apps, and Managed Apple Accounts at scale. Serval connects to the Apple Business Manager API using an ABM API account, so your workflows can assign or unassign devices to MDM servers, ingest your organization’s devices into Serval asset management, and reach anything else Apple’s Business Manager API offers. No browser sign-in is involved - the connection runs entirely on credentials you create inside Apple Business Manager. Authentication: ABM API account (Client ID + Key ID + EC private key). Each time Serval calls Apple on your behalf, it signs a short-lived token with your private key and exchanges it with Apple for access - and what the integration can do is governed by the API account’s role in ABM. Data sync: On-demand. The shipped “Ingest Computers from Apple Business Manager” workflow pages through your organization’s devices and syncs them into Serval asset management; everything else runs only when a workflow calls it. There is no other background sync.

​
What the Apple Business Manager integration enables

Anything defined in the Apple Business Manager API can be accessed through Serval.

​
Get your credentials

You need an API account in Apple Business Manager with a generated private key. Only users with the Administrator role in ABM can create API accounts. Apple’s official guide: Create an API account in Apple Business Manager.
1

Sign in to Apple Business Manager

Go to business.apple.com and sign in with an Administrator account.
2

Open the API preferences

Click your name at the bottom of the sidebar, select Preferences, then select API.
3

Create the API account

Click Get Started, enter a name for the account (e.g. “Serval Integration”), then click Create.
4

Generate and download the private key

Click Generate Private Key to download the .pem private key file.
5

Copy the Client ID and Key ID

Click Manage to view the Client ID and Key ID - you need both, plus the contents of the .pem file, for Serval.
The .pem private key downloads exactly once, at generation time. Store it securely. If you lose it, you must generate a new key in ABM - which gets a new Key ID - and update Serval with both.
The key Apple generates is an EC P-256 key, which is exactly what Serval requires. Don’t substitute a key from another system - RSA keys are rejected.

​
Connect in Serval

All three fields are required - the form won’t accept a blank value for any of them.
1

Enter your Client ID

Client ID. Helper text: “Your Apple Business Manager Client ID (format: BUSINESSAPI.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)”.
2

Enter your Key ID

Key ID. Helper text: “Your Apple Business Manager Key ID”. It’s shown next to your key in ABM under Preferences → API → Manage.
3

Paste your Private Key

Private Key (multiline password field). Helper text: “Paste the contents of your .pem private key file”. Paste the entire file, including the “-----BEGIN PRIVATE KEY-----” and “-----END PRIVATE KEY-----” lines, with no extra whitespace.
4

Save and test

Submit the form, then run the connection health check (below). Serval doesn’t parse the key when you save - a bad paste only surfaces when the connection is tested or used, so always run the health check after connecting.
Editing an existing connection: Client ID and Key ID must stay filled in - an update without either is rejected. The Private Key field shows a read-only masked value (bullets plus the last 4 characters of the stored key) with a Replace button; save without clicking Replace and your stored key is kept unchanged. To rotate the key, click Replace and paste the entire contents of the new .pem file.

​
Verifying the connection

The integration ships one health check: Test Apple Business Manager Connection - requests a single device from your organization through Serval, verifying the full chain: private key parsing, token signing, the token exchange with Apple, and an authenticated API call to Apple Business Manager.
  • On success: “Successfully authenticated with Apple Business Manager and retrieved device data”
  • On failure: “Unable to connect to Apple Business Manager. Please verify your Client ID and private key are correct. Common issues: invalid EC P-256 private key format, incorrect Client ID, or insufficient API permissions.”
A green health check proves authentication works - it does not prove your API account can do everything your workflows need. Serval configures no scopes of its own; permissions come entirely from the API account’s role inside Apple Business Manager. If the test passes but a workflow fails, check the API account’s permissions in ABM first.

​
Gotchas and troubleshooting

Serval requires the exact key type that ABM’s Generate Private Key produces. Paste the entire .pem contents including the “-----BEGIN PRIVATE KEY-----” and “-----END PRIVATE KEY-----” lines, with no extra whitespace. A malformed paste fails with an error that includes “failed to decode PEM block: ensure the private key starts with ‘-----BEGIN PRIVATE KEY-----’ and ends with ‘-----END PRIVATE KEY-----’”. RSA or other key types fail with “private key is not EC format (Apple Business Manager requires an EC P-256 key)”. These errors appear when the connection is tested or used - not when you save the form - so run the health check right after connecting or rotating the key.
Updates re-validate Client ID and Key ID, so both must be present whenever you save changes. The Private Key field shows a read-only masked value with a Replace button; saving without replacing it keeps the stored key. To rotate, click Replace and paste the complete new .pem contents. Serval doesn’t validate the new key at save time, so a partial or wrong paste only shows up when the connection is next used - re-run the health check after every rotation.
Connections created before Key ID support stored only a Client ID. These fail with an error that includes “Apple Business Manager integration is missing Key ID, please reconfigure with your Key ID from Apple Business Manager → Preferences → API”. Fix by editing the connection and adding the Key ID (re-paste the private key only if you’re also rotating it).
ABM only offers the .pem at generation time. If it’s lost, generate a new key in ABM - it gets a new Key ID - and update the Serval connection with both the new Key ID and the new key. The Key ID must always match the private key in use.
Serval installs this integration with no scopes of its own; access tokens are requested with Apple’s fixed “business.api” scope. What the integration can actually read or change is governed by the API account’s role and permissions inside Apple Business Manager. If calls are denied despite a passing health check, adjust the API account in ABM.
The generic API action is a raw wrapper around Apple’s Business Manager API with no built-in endpoint catalog. There is no separate field for path parameters: build the final path string yourself before sending. A path still containing a literal {param} placeholder is sent to Apple unmodified and will fail.
The “Assign or Unassign Device in Apple Business Manager” workflow looks up your MDM servers and matches the target by display name (case-insensitive). If no server matches, the workflow errors and lists the available server names - copy the name exactly as it appears in that list.
Need help? Contact support@serval.com for assistance with your Apple Business Manager integration.